Angular JS From a Different Angle!

I recently made the switch to a full-stack JavaScript front end framework for an enterprise application that we are building.

In this post, I’ll talk about the integration (or, rather lack thereof) of the development methodologies used for developing a server-side RESTful API vs. a client side Angular JS applications. Along the way, I’ll add some opinion to the already opinionated Angular framework.

First, let’s look why Javascript is relevant today.

The graphic below nicely shows the evolution of Javascript from ad-hoc snippets to libraries to frameworks. Of these frameworks, Angular seemed to be getting a lot of traction (being pushed by Google helps Image may be NSFW.
Clik here to view. ).

Image may be NSFW.
Clik here to view.

As we can see, we went from ad-hoc javascript code snippets to libraries to full fledged frameworks. It stands to reason, then that these frameworks be subject to the same development rigor that is accorded server-side development. In achieving that objective, we see tho’ that integration of tools that enforce that rigor, is not all that seamless.

Angular JS development is what I would call web-centric. That makes sense, given that it runs in a browser! However, if we focus all our energies in building services (exposed via an API, RESTful or not); and a web front-end is just one of many ways that my services are consumed, in that scenario, the web-centric nature of Angular development can get a bit non-intuitive.

For a server-side developer, when starting with the Angular stack, issues like the following can become a hinderance:

Where’s the data coming from?

If you want to run most of Angular’s samples you need to fire up a Node JS server. Not that that is something insurmountable. But I didn’t sign up for NodeJS, just Angular. Now I have to read thru Node docs to get samples up and running.

Next, testing:

Testing or rather, the ability to write tests, has a big role to play in the Javascript renaissance. Well..ok.. let’s write some tests! But wait! I need to install PhantomJS or NodeJS or some such JS server to fire up the test harness! Oh, crap! Now I’ve got to read up on Karma (aka Testacular) to run the tests.

What about the build:

How do I build my Angular app. Well… the docs and samples say.. use npm. What’s that? So now I’ve to google and start to use the Node Package Manager to download all dependencies. Or get Grunt! (Grunt!)

All I want to do is bolt on an Angular front-end to an existing REST endpoint. Why do I need all this extra stuff?  Well.. that is because Angular takes a web-centric approach and is largely influenced by the Rails folks (See my related post here), whereas enterprise services treat the front-end as an after-thought Image may be NSFW.
Clik here to view.

So, before I get all the Angular (and Ruby on Rails) fans all worked up, here’s the good news!

I wrote up an application that bolts on an Angular JS front-end to a Java EE CRUD application (Spring, Hibernate.. the usual suspects) on the back-end. It’s a sample therefore it obviously lacks certain niceties like security, but it does make adoption of Angular easier for someone more familiar with Java EE than Ruby on Rails.

Source and Demo

You can download and check out Angular EE (aka PointyPatient) here. In the rest of this post, I’ll refer to this sample app, so it may help to load it up in your IDE.

You can also see the app in action here.

Opinions, Opinions

One of Angular’s strengths is that it is an opinionated framework. In the cowboy-ruled landscape of the Javascript of yore, opinion is a good thing! In Angular EE, you will see that I’ve added some more opinion on top of that, to make it palatable to the Java EE folks!

So here is a list of my opinions that you will see in Angular EE:

Angular Structure

The structure of an webapp is largely predicated on if it is a servlet or not. Besides the servlet specification that mandates the existence of  a web.xml, all other webapp structures are a matter of convention. The Angular sample app, Angular-Seed,  is not a servlet. Notwithstanding the fact that Angular (and all modern front-end frameworks) are pushing for a Single Page App (SPA), I still find servlets a very alluring paradigm. So here’s my first opinion. Rather than go for a SPA, I’ve made Angular EE’s web application a servlet that is also an SPA.

If you compare the directory structure on the left (Angular-Seed) with the one on the right (PointyPatient webapp), you will see that the one on the right is a servlet that has a WEB-INF/web.xml resource. It also has an index.html at the root. This index.html does nothing but a redirect like so:

<meta HTTP-EQUIV=”REFRESH” content=”0; url=app/index.html”>

Image may be NSFW.
Clik here to view.Image may be NSFW.
Clik here to view.

It is the index.html inside the app directory that bootstraps the angular app. And so the context root of the webapp is still the webapp directory, not webapp/app.

So what’s the advantage of making this a servlet? For one: You can use the powerful servlet filtering mechanism for any pre-processing that you may want to do on the server,  before the SPA is fired up. The web.xml is the touchpoint where you would configure all servlet filters.

For seconds, instead of having one SPA, would it not be nice if one webapp would serve up several “SPA”s?

For example, let’s say you have an application that manages patients, doctors and their medication in several hospitals. I can easily see the following SPAs:

• Bed Management
• Patient- Drug interaction
• Patient-Doc Configuration
• Patient Records

Usually, a user will use only one SPA , but on occasion will need to cross over to a different SPA. All the above SPA’s share a common http session, authentication and authorization.  The user can switch between them without having to log on repeatedly. Why load up all the functionality in a browser when only a subsystem may be needed? Use server-side (servlet) features to decide which SPAs to fire-up depending on who’s logged in (using authorization, roles, permissions etc). Delay the loading of rarely used SPAs as much as possible.

For the above reasons, I think it is a good idea to serve up your SPA (or SPAs) within the context of a servlet.

Now let’s look at the structure of just the Angular part:

Image may be NSFW.
Clik here to view.Image may be NSFW.
Clik here to view.Again, on the left is AngularSeed and on the right, PointyPatient.

There is no major change here except I prefer views to partials (in keeping with the MVVM model)

And secondly, I preferred to break out controllers, services,directives and filters into their own files. This will definitely lead to less Source Control problems with merges.

app.js still remains the gateway into the application with routes and config defined there. (More on that later).

.

Project Structure

Now that we have looked at differences in the Angular app, let’s step back a little and look at the larger context: The server-side components. This becomes important, only because we want to treat the Angular app as just another module in our overall project.

I am using a multi-module Maven project structure and so I define my Angular app as just another module.

Image may be NSFW.
Clik here to view.

• Pointy-api is the Rest Endpoint to my services
• Pointy-build is a pom project aggregate the maven reactor build.
• Pointy-domain is where my domain model (hopefully rich) is stored
• Pointy-parent is a pom project for inheriting child projects
• Pointy-services is where the business logic resides and is the center of my app.
• Pointy-web is our Angular app and the focus of our discussion

Anatomy of the Angular App

A Java EE applications has layers that represent separation of concerns. There is no reason we cannot adopt the same approach on the Angular stack also.

As we see in the picture below, each layer is unilaterally coupled with it’s neighbor. But the key here is dependency injection. IMO, Angular’s killer feature is how it declares dependencies in each of it’s classes and tests (more on that later). PointyPatient takes advantage of that as can be seen here.

Image may be NSFW.
Clik here to view.

Let is discuss each layer in turn:

Views: HTML snippets (aka partials). There is no “logic” or conditionals here. All the logic is buried either in Angular provided directives or your own directives. An example would be the use of the ng-show directive on the alert directive in the Patient.html view. Conditional logic to show/hide the alert is governed by two-way binding on the view-model that is passed to the directive. No logic means no testing of the view. This is highly desirable because the view is mainly the DOM and the DOM is the most difficult/brittle to test.

Controllers: Although, it may seem by looking at some of the samples, that we should end up with a controller per view, in my opinion, a controller should be aligned to a view-model, not a view. So in PointyPatient we see that we have one controller (PatientController) that serves up both the views (Patient.html and PatientList.html) because the view-model for both these views do not interfere with each other.

Services: Here we see common logic that is not dependent on a view-model is processed.

• Server-side access is achieved via Restangular. Restangular returns a promise which is passed to the controller layer
• An example of business logic that would make sense in this layer would be massaging Restangular returned data by inspecting user permissions for UI behavior. Or date conversions for UI display. Or enhancing JSON that is returned by the db with javascript methods that can be called in the view (color change etc).
  There is a subtle difference between the client and server-side service layers: The client-side service layer holds business logic that is UI related, yet not the view-model related. Server-side service layer holds business logic that should have nothing to do with the UI at all.
• Keep the view-model (usually the $scope object) completely decoupled from this layer.
• Since services return a promise, it is advisable to not process the error part of a promise here, but pass it on to the controller. By doing so, the controller will be well suited to change the route or show user appropriate messages based on the processing of the error block from a promise. This can be seen in PatientController and PatientService

Layers

Since we have defined layers on both, the Angular stack and the server-side, an example may help solidify the purpose of the layers. So, using this rather contrived example in the medical area, here are some sample APIs in each layer:

Server side services:
This is where ‘business logic’ that is UI independent lives.

• Invoice calculatePatientInvoice(Long patientId);
• boolean checkDrugInteractions(Long patientId, Long prescriptionId);
• boolean checkBedAvailability(patientId, LodgingPreference preference);
• List<Patient> getCriticalPatients();
• int computeDaysToLive(Long patientId);

The number of days a patient lives will not depend on if we use Angular for the UI or not Image may be NSFW.
Clik here to view. . It will depend, tho’ on several other APIs available only on the server-side (getVitals(), getAncestoralHistory() etc..).
Server Side controllers:
If we use Spring MVC to expose services via REST, then the controllers are a very thin layer.
There is no business logic at all. Just methods that expose the REST verbs which call the services in turn.

• getPatientList();
• getPatient(Long patientId);
• createPatient(Patient patient);
• deletePatient(Long patientId);

Angular services:
This is where ‘business logic’ that is UI dependent lies.
These are used by several angular controllers. This could involve cached JSON massaging or even servers-side calls. However, processing is always UI related.

• highlightPatientsForCurrentDoctorAndBed();
  Assuming that doctorId and bedId are JSON data in the browser, this method changes the color of all patients assigned to the current doc and bed.
• showDaysAgoBasedOnLocale(date);
  Returns 3 days ago, 5 hours ago etc instead of a date on the UI.
• computeTableHeadersBasedOnUserPermission(userId);
  Depending on who’s logged in, grid/table headers may need to show more/less columns.
  Note that it is the server based service that is responsible for hiding sensitive data based on userId.
• assignInvoiceOverageColor(invoice);
  Make invoices that are over 90 days overdue, red, for instance.
• showModifiedMenuBasedOnPermissions(userId);
  Hide/disable menus based on user permissions (most likely cached in the browser).
• computeColumnWidthBasedOnDevice(deviceId);
  If a tablet is being used, this nugget of info, will most likely be cached in the browser.
  This method will react to this info.

Angular controllers:
These methods are view-model ($scope) dependent. These are numerous and shallow.
Their purpose in life is to handle (route) error conditions and assign results to the scope.

• getDoctorForPatient(Long patientId);
  This massages local(in-browser) patient-doctor data, or can access to the server via Angular services -> REST -> Server Services and assigns to a scope variable.
• getEmptyBedsInZone(zoneId);
  scope assignment of the beds

The main difference is that here the result is assigned to the $scope, unlike the Angular Service, which is $scope independent.

Testing

While most JS Frameworks emphasize the importance of testing Javascript (and there are enough JS Testing frameworks out there), IMO, it’s only Angular that focusses on a key enabler for meaningful unit testing: Dependency Injection.

In PointyPatient, we can see how Jasmine tests are written for Controllers and Services. Correspondingly, JUnit tests are written using Spring Testing Framework and Mockito.

Let’s look at each type of test. It may help to checkout the code alongside:

1. Angular Controller Unit tests: Here the system under test is the PatientController. I have preferred to place all tests that pertain to PatientController in one file, PatientControllerSpec.js,  as against squishing all classes’ tests in one giant file, ControllerSpec.js. (Works from the Source control perspective also). The PatientService class has been stubbed out by using a jasmine spy. The other noteworthy point is the use of the $digest() function on the $rootScope. This is necessary because the call to patientService returns a promise that is typically assigned to a $scope variable. Since $scope is evaluated when the DOM is processed (apply()‘ed), and since there is no DOM in the case of a test, the $digest() function needs to be called on the rootScope (I am not sure why localScope.$digest() doesn’t work tho’).
2. Angular Service Unit Tests: Here the system under test in the PatientService. Similar to PatientControllerSpec.js, PatientServiceSpec.js only caters to code in PatientService.js. Restangular, the service that gets data from the server via RESTful services, is stubbed out using Jasmine spies.
   Both the PatientControllerSpec.js and PatientServiceSpec.js can be tested using the SpecRunner.html test harness using the file:/// protocol.
   However, when the same tests are to be run with the build, see the config of the jasmine-maven-plugin in the pom.xml of the pointy-web project. The only word of caution here is the order of the external dependencies that the tests depend on and which are configured in the plugin. If that order is not correct, errors can be very cryptic and difficult to debug.
   These tests (Unit tests) can therefore be executed using file:///…/SpecRunner.html during development and via the maven plugin during CI.
   In this sense, we have run these unit tests without using the Karma Test Runner, because, in the end, all the Karma test runner does, in the context of an Angular unit test is to watch for changes in your JS files. If you are ok, with not needing that convenience, then Karma is not really necessary.
3. End-To-End Tests: These tests are run using a combination of things:
   First, note the class called: E2ETests.java. This is actually a JUnit test that is configured to run using the maven-failsafe-plugin in the integration-test phase of the maven life-cycle.
   But before the failsafe plugin is fired up, in the pre-integration-test phase, the maven-jetty-plugin is configured to fire up a servlet container that actually serves up the Angular servlet webapp (pointy-web) and the RESTful api webapp (pointy-api), and then stops both in the post-integration-test phase.
   E2ETests.java loads up a Selenium driver, fires up Firefox, points the browser url to the one where Jetty is running the servlet container (See pointy-web’s pom.xml and the config of the maven-jetty-plugin).
   Next we can see in scenario.js, we have used the Angular supplied API that navigates the DOM. Here we navigate to a landing page and then interact with input elements and traverse the DOM by using jQuery.
   If we were to run these tests using the Karma E2E test harness, we see that Karma runs the E2E test as soon as the scenario.js file changes. A similar (but not same) behavior can be simulated by running
   mvn install -Dtest=E2ETests
   on the command line.
   It is true, tho’ that running tests using maven will take  much longer to run than it’s Karma counterpart because Maven has to go thru its lifecycle phases, up until the integration-test phase.
   But if we adopt the approach that we write a few E2E tests to test the happy-path and several unit tests to maximize test coverage, we can mitigate this disadvantage.
   However, as far as brittleness is concerned, this mechanism (using Selenium)  is as brittle (or as tolerant) than the corresponding Karma approach, because ultimately, they both fire up a browser and traverse the DOM using jQuery.
4. Restangular is not tested within our application because it’s an external dependency, altho it manifests as a separate layer in our application.
5. On the server-side we see the Spring MVC Test Integration that is part of the Spring 3.2+ framework. This loads up the web-application context including security (and all other filters, including the CORS filter) that are configured in the web.xml. This is obviously slow (because of the context being loaded) and therefore we should use it only for testing the happy path. Since these tests do not rollback db actions, we must take care to set-up and tear-down our test fixtures.
6. Next we have the Spring Transactional Tests. These integration tests use the Spring Test Runner which ensures that db transactions are rolled back after each test. Therefore tear-downs are not really needed. However, since the application context is loaded up on each run, these tend to be slow runners and must be used to test the happy path.
7. Next we have Service Unit tests: PatientServiceTests.java: These are unit tests that use the Mockito test library to stub out the Repository layer. These are written to maximize test coverage and therefore will need to be numerous.
8. Repository Unit tests (PatientRepositoryTests.java) are unit tests that stub out calls to the database by replacing the spring datasource context by a test-datasource-context.xml

Environmentally Aware!

Applications need to run in various ‘environment’s like, development, test, qa and production. Each environment has certain ‘endpoints’ (db urls, user credentials, JMS queues etc)  that are typically stored in property files. On the server side, the maven build system can be used to inject these properties into the ‘built’ (aka compiled or packaged) code. In the case of using Springframework, a very nice interface PropertyPlaceholderConfigurer can be used to inject the correct property file using Maven profiles. (I’ve blogged previously about this here). An example of this is the pointy-services/src/main/resources/prod.properties property file that is used when the -Pprod profile is invoked during the build.
The advantage of this approach is that properties can be read from a hierarchy of property files at runtime.

In AngularEE, I have extended this ability of making the code ‘environmentally aware’ in the JS stack also. However, property injection happens only at buildtime. This is affected using Maven profiles as can be seen in pom.xml of pointy-parent module. In addition, please see the environment specific property files in pointy-web/src/main/resources. Lastly, check out the customization of the maven-war-plugin where the correct ${env}.property file is filtered into the war at build time. You will see how the REST endpoint is injected into the built war module in app.js for different environments.

In summary

We have seen how we can use a homogenous development environment for building an Angular application. Since user stories slice vertically across the entire stack, there is value in striving for that homogeneity so that if a story is approved (or rolled back), it affects the entire stack, from Angular all the way to the Repository.

We have also seen a more crystalized separation of concerns in the layers that are defined in the Angular stack.

We have seen how the same test harness can be used for server and client side tests.

Lastly we have seen how to make the Angular app aware of the environment it runs in, much like property injection on the server side.

I hope this helps more Java EE folks in adopting Angular JS, which I feel is a terrific way to build a web front end for your apps!

References

• http://blog.akquinet.de/2011/02/11/mavenizing-javascript-projects/
• https://www.youtube.com/watch?v=Qo0XCz-neNs