Paul Samsotha Blog

Absolute Paths with Angular and Webpack

Sat, 18 Mar 2017 00:00:00 -0700

When using Angular with TypeScript, we’re always importing files into other files. An import statement might look something like

import { Data } from '../data';

If you are very picky about style, then you might be repulsed at seeing something like the following, when you have deeply nested files

import { Data } from '../../../data';

We are not strictly tied to using this way of relative importing though. In this article, I will briefly explain how we can use absolute file paths for imports, so you that with the following file structure

src/
    + app/
    |  |
    |  `- constants.ts
    |
    + message/
      |
      `- model/
          |
          `- message.ts

in your message.ts file, you can do this

import { DEFAULT_MESSAGE } from 'src/app/constants';

which is IMO is much more preferable than doing

import { DEFAULT_MESSAGE } from '../../app/constants';

To begin, please have a look at this GitHub repo. It is basically just the project from the Angular Webapack docs, with a few modifications.

In the project, you will see the previously mentioned file structure. You may not have this same file structure in your application (for instance you may keep all your app folders inside the app directory), but hopefully after reading this article, you will be able to figure out how to adjust configurations accordingly to fit your application structure.

So to get this working there are two steps we need to take. First we need to make a simple modification to the TypeScript tsconfig.json file, and second we beed to make a small modification to the Webpack webpack.config.js file

tsconfig.json

The only thing we need to configure for TypeScript is to set the baseUrl property in the compilerOptions

"compilerOptions": {
  "baseUrl": ".",
}

The baseUrl property is stated in the compilerOptions to be:

Base directory to resolve non-relative module names

So if we don’t use this property, then all of our module imports will be relative. So we can only use the ./ syntax. But now we are saying that “aside from relative paths, look at the . (base) directory. So now if we use

import { DEFAULT_MESSAGE } from 'src/app/constants';

src is in the base directory, so TypeScript will be able to resolve the file using this absolute path.

Or if you wanted, you could even do

"compilerOptions": {
  "baseUrl": "./src",
}

This would allow you to get rid of the src from the import

import { DEFAULT_MESSAGE } from 'app/constants';

webpack.config.js

The configuration for Webpack is pretty easy also. What we want to do is modify the resolve.modules. In your project, you might just have

module.exports = {
  resolve: {
    extensions: ['.js', '.ts']
  }
}

But there are other properties on the resolve that we can configure (see link below for more). For this case we just want to configure the module property to tell Webpack where else to resolve modules from besides just the node_modules

modules: [
  '../',
  '../node_modules'
]

Or if you’re going of the project, you can use the `helpers utility.

modules: [
  helpers.root('/'),
  helpers.root('node_modules')
]

Here we are telling Webpack to use both the root directory and the node_modules. We need to specify the node_modules since we are overriding the default.

One thing to note about the project is that is uses a config directory t store all the configuration files. This is why we need to go a level up ../ to resolve, as it’s being resolved from the location of the configuration file. If you are only using one webpack.config.js file or even multiple that are in the root directory, then we don’t need to go a level up. You can just do

modules: [
  path.resolve('.'),
  'node_modules'
]

Resources

Jersey Pagination With Spring Data JPA

Sat, 07 Jan 2017 00:00:00 -0800

Applications that deal with retrieving and displaying data, will often run into situations where retrieving an entire dataset is just not efficient. For example, say that a database contains data for 1,000 products. On the client side, you want to display the products, but will only be displaying 25 products at a time. There will be links to next pages that will display more products. It would be inefficient to grab all 1,000 products, especially if the user never even goes past the first page. This is one of the cases where pagination of data would be appropriate.

Pagination in the context of data, is basically the process of splitting a dataset into multiple pages (or “block” of results), with a set size for each page. To get the next set of results, we would just change the “page” query parameter. Assuming you have some experience working with JPA (Java Persistence API), what that might look in code is something like

public List<Product> getProducts(int page, int size) {
    return this.entityManager.createNamedQuery("Product.findAll", Product.class)
        .setFirstResult(page * size)
        .setMaxResults(size)
        .getResultList();
}

The above code is a just a method in some arbitrary service class that has access to the EntityManager. The call to setFirstResult determines the first result that is returned. This allows use to paginate by multiplying the supplied page by the size of each page. The size of the result set is determined by the value passed to setMaxResults. If 0 is passed as the page, and the size passed is 5, then the first result would be the 0^th result, and the size of the result set would be five. If 1 was passed as the page and 5 as the size then the first result would be the 5^th and the result set would be the 5^th through 9^th.

This is pretty much how we can do pagination with vanilla JPA. This article though, will not be using vanilla JPA. My personal goto persistence framework is Spring Data JPA, which is a Spring-based abstraction layer over vanilla JPA, offering easier data management strategies. If you are unfamiliar with Spring Data, please read the previous linked documentation. You may also be interested in a previous article Why and How to Use Spring with Jersey.

Note: The source code for the examples in the article can be found in this GitHub project.

When working with Spring Data JPA, we are able to simply extend an interface (JpaRepository) with an interface of our own, and Spring Data will provide implementations for some basic CRUD and paging method implementations. For example, take this interface:

public interface CustomerRepository extends JpaRepository<Customer, Long> {}

The JpaRepository defines (or more precisely, inherits) methods such as

List<T> findAll();

T save(T t);

void delete(T t);

where T is the entity type (in this case Customer). These are not the only methods defined though. There are a bunch more. And we do not need to implement these. These are all implemented by Spring Data. Along with the “vanilla” findAll method, there is also a “pageable” version defined:

Page<T> findAll(Pageable pageable);

This allows us to pass a Pageable instance and returns to us a Page. An implementation of the Pageable interface is the PageRequest, which has the following overloaded constructors:

PageRequest(int page, int size)

PageRequest(int page, int size, Sort.Direction direction, String... properties)

PageRequest(int page, int size, Sort sort)

The first constructor allows us to simply pass the page and size, just like in our vanilla JPA example. The next two constructors allow for sorting of the pre-paged results. The sorting is based on properties on the entity, and Sort.Direction specifies the direction of the sort, either ascending or descending. In our example, we will use the third constructor which allows us to pass a Sort instance.

Let’s now implement our resource class, that makes use of the CustomerRepository. The paging and sorting parameters will be passed as query parameters. An example URL will be

http://localhost:8080/api/customers?page=1&size=2&sort=firstName,DESC

Here, the result will be the second page, with two results, sorted by the first name, in descending order. The following is our first implementation of the resource class:

@Path("customers")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class CustomerResource {

    private final CustomerRepository repository;

    @Autowired
    public CustomerResource(CustomerRepository repository) {
        this.repository = repository;
    }

    @GET
    public Response getAllCustomers(
            @QueryParam("page") @DefaultValue("0") Integer page,
            @QueryParam("size") @DefaultValue("3") Integer size,
            @QueryParam("sort") List<String> sort) {

        List<Sort.Order> orders = new ArrayList<>();
        for (String propOrder: sort) {
            String[] propOrderSplit = propOrder.split(",");
            String property = propOrderSplit[0]);
            if (propOrderSplit.length == 1) {
                orders.add(new Sort.Order(property));
            } else {
                Sort.Direction direction
                        = Sort.Direction.fromStringOrNull(propOrderSplit[1]);
                orders.add(new Sort.Order(direction, property));
            }
        }

        Pageable pageable = new PageRequest(page, size,
                orders.isEmpty() ? null : new Sort(orders));

        List<Customer> customers = repository.findAll(pageable).getContent(); 
        return Response.ok(new GenericEntity<List<Customer>>(customers) {}).build();
    }
}

The sort query parameter can be used multiple times like

sort=firstName&sort=lastName,DESC

so we accept a List<String> as the parameter type. We want to turn that List<String> into a List<Sort.Order>, as that’s what the Sort constructor takes. Remember, we are using the third PageRequest constructor that accepts a Sort instance. Once we have the list, we create the PageRequest and pass it to the findAll method.

The result of the findAll call, will be a Page<Customer> instance. Here we are just getting the content of the page, which is the List<Customer>. If we wanted to create some HATEOAS links, we could use the other properties on the Page. But we won’t be discussing HATEOAS here, so we just return the content.

This example works fine, but we can improve it. There’s not much wrong with the code itself, but the problem is that we would have to do this for every resource method where we wanted to add paging. We could create a helper/utility class, but we would still have to accept the @QueryParams to the resource method, then pass them to the helper. Ideally, we would rather be able to do something like

@GET
public Response getAllCustomers(@Pagination Pageable pageable) {
    List<Customer> customers = repository.findAll(pageable).getContent();
    return Response.ok(new GenericEntity<List<Customer>>(customers) {}).build();
}

where the Pageable is transparently created and passed to us. In Jersey, we can do this with a ValueFactoryProvider, which is the SPI we need to implement to tell Jersey that we want to create an injectable method parameter. The following is an implementation we can use for the Pageable

public class PageableValueFactoryProvider implements ValueFactoryProvider {

    private final ServiceLocator locator;

    @Inject
    public PageableValueFactoryProvider(ServiceLocator locator) {
        this.locator = locator;
    }

    @Override
    public Factory<?> getValueFactory(Parameter parameter) {
        if (parameter.getRawType() == Pageable.class
                && parameter.isAnnotationPresent(Pagination.class)) {
            Factory<?> factory = new PageableValueFactory(locator);
            return factory;
        }
        return null;
    }

    @Override
    public PriorityType getPriority() {
        return Priority.NORMAL;
    }

    private static class PageableValueFactory
            extends AbstractContainerRequestValueFactory<Pageable> {

        @QueryParam("page") @DefaultValue("0") Integer page;
        @QueryParam("size") @DefaultValue("3") Integer size;
        @QueryParam("sort") List<String> sort;

        private final ServiceLocator locator;

        private PageableValueFactory(ServiceLocator locator) {
            this.locator = locator;
        }

        @Override
        public Pageable provide() {
            locator.inject(this);

            List<Sort.Order> orders = new ArrayList<>();
            for (String propOrder: sort) {
                String[] propOrderSplit = propOrder.split(",");
                String property = propOrderSplit[0];
                if (propOrderSplit.length == 1) {
                    orders.add(new Sort.Order(property));
                } else {
                    Sort.Direction direction
                            = Sort.Direction.fromStringOrNull(propOrderSplit[1]);
                    orders.add(new Sort.Order(direction, property));
                }
            }

            return new PageRequest(page, size,
                      orders.isEmpty() ? null : new Sort(orders));
        }
    }
}

The main method of the ValueFactoryProvider SPI, is the createValueFactory method

@Override
public Factory<?> getValueFactory(Parameter parameter) {
    if (parameter.getRawType() == Pageable.class
            && parameter.isAnnotationPresent(Pagination.class)) {
        Factory<?> factory = new PageableValueFactory(locator);
        return factory;
    }
    return null;
}

In order for Jersey to see if it can handle a method parameter, it will call all the ValueFactoryProviders, and call their getValueFactory methods. If the ValueFactoryProvider can handle the parameter, it should return a Factory, otherwise it should return null. In our implementation we are saying that we can handle parameters of type Pageable that are annotated with @Pagination (which is a custom annotation)

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Pagination {
}

The PageableValueFactory is our Factory implementation. This will be where we create the Pageable

private static class PageableValueFactory
        extends AbstractContainerRequestValueFactory<Pageable> {

    @QueryParam("page") @DefaultValue("0") Integer page;
    @QueryParam("size") @DefaultValue("3") Integer size;
    @QueryParam("sort") List<String> sort;

    private final ServiceLocator locator;

    private PageableValueFactory(ServiceLocator locator) {
        this.locator = locator;
    }

    @Override
    public Pageable provide() {
        locator.inject(this);

        List<Sort.Order> orders = new ArrayList<>();
        for (String propOrder: sort) {
            String[] propOrderSplit = propOrder.split(",");
            String property = propOrderSplit[0];
            if (propOrderSplit.length == 1) {
                orders.add(new Sort.Order(property));
            } else {
                Sort.Direction direction
                        = Sort.Direction.fromStringOrNull(propOrderSplit[1]);
                orders.add(new Sort.Order(direction, property));
            }
        }

        return new PageRequest(page, size,
                orders.isEmpty() ? null : new Sort(orders));
    }
}

One interesting thing about @QueryParam, @PathParam and other @XxxParam, is that they can also be injected into fields (instead of what you would normally see as method parameters). So here, we are injecting them into this Factory implementation. A new factory will be created for each request, so we don’t need to worry about any concurrency issues. The only catch here, is that we need to explicitly inject it with the ServiceLocator. The reason is that Jersey will not inject it for us.

Now that we have our implementation, the last thing is just to register the provider with Jersey

@ApplicationPath("/api")
public class AppConfig extends ResourceConfig {
    
    public AppConfig() {
        packages("com.example");
        register(new AbstractBinder() {
            @Override
            protected void configure() {
                bind(PageableValueFactoryProvider.class)
                        .to(ValueFactoryProvider.class)
                        .in(Singleton.class);
            }
        });
    }
}

And now we can do the following for any resource method that wants the Pageable

@GET
public Response getAllCustomers(@Pagination Pageable pageable) {
    List<Customer> customers = repository.findAll(pageable).getContent();
    return Response.ok(new GenericEntity<List<Customer>>(customers) {}).build();
}

Note

Earlier in this article, I mentioned something about HATEOAS and working with the Page object. The example above doesn’t do anything with the Page object, and just returns the List content. Normally when working with pagination, you want to provide details to the client on what the next or previous page will be, or whether there is a next, and things like that. This is where HATEOAS comes to play. Instead of just returning the list, you may want to provide links to next and previous URLs. For instance

http://localhost:8080/api/customers

{
  "_links": {
    "next": "/api/customers?page=1&size=5",
      "prev": null
  },
  "content": [ ..first five (default size) results.. ]
}

This is just an example. HATEOAS is implemented in different ways. There is not just one correct way. I am not going to get into the details, but HATEOAS is definitely something to consider, and research to see if it’s the right fit for your application.

Using Effects in an Angular 2 NgRx Application

Sat, 31 Dec 2016 00:00:00 -0800

The first step in getting started with NgRx is to introduce Store in to the application, which is more than just a class, but a whole new way of thinking about state in our Angular applications. This article does not attempt to explain much about Store. If you don’t have any experience working with Store, please take some time to visit Comprehensive Introduction to @ngrx/store. The linked article IMO is the best out there for anyone new. It is as comprehensive as it gets. To get the most out of it, I recommend coding along.

In this article, I will introduce the NgRx Effects library, which is a compliment to Store. I will first do a quick walk through of what a simple login solution might look like only using Store, then I will introduce Effects into the mix. The main goal is get a clearer picture of how Effects actually fits in, and point out some of the benefits. The hardest part for me when starting, was to actually wrap my head around how it all fit together, so that’s what I will do here: try to explain my understandings.

Note: There is a complimentary example project to go along with this article. You can clone it from GitHub.

Let’s first explain the problem domain. We want to create a simple login and then display the user after they have successfully logged in. The username display will first show the user as anonymous, then after login, show the user name and avatar. The result will look like the following:

We’ll first start by implementing this without using Effects. If you look at the @ngrx/store project README, you’ll see the following description about the project:

@ngrx/store is a controlled state container designed to help write performant, consistent applications on top of Angular. Core tenets:

State is a single immutable data structure

Actions describe state changes

Pure functions called reducers take the previous state and the next action to compute the new state

State accessed with the Store, an observable of state and an observer of actions

If you have worked with Store (which you should already have, if you are following along), these concepts should be familiar to you. So let’s break each down into code.

In our simple login application, we will have only one state, which is the user state. The UserState will have the following properties

export interface UserState {
  id: number;
  username: string;
  imageUrl: string;
  status: string;
}

As for the action that “describe[s] state changes” we will (for now) just have two actions, LOAD_USER_FAILURE and LOAD_USER_SUCCESS, and here is our action creator class

export class UserActions {
  static readonly LOAD_USER_FAILURE = 'LOAD_USER_FAILURE';
  static readonly LOAD_USER_SUCCESS = 'LOAD_USER_SUCCESS';


  loadUserSuccess(user: UserData): Action {
    return {
      type: UserActions.LOAD_USER_SUCCESS,
      payload: {
        user
      }
    };
  }

  loadUserFailure(message: string): Action {
    return {
      type: UserActions.LOAD_USER_FAILURE,
      payload: {
        message
      }
    };
  }
}

Now for the reducer

const initialState: UserState = new UserRecord() as UserState;

export const userReducer: ActionReducer<UserState>
    = (state = initialState, {type, payload}: Action) => {
  switch (type) {
    case UserActions.LOAD_USER_SUCCESS:
      const { user } = payload;
      return state.withMutations(currentUser => {
        currentUser
          .set('id', user.id)
          .set('username', user.username)
          .set('imageUrl', user.imageUrl)
          .set('status', USER_LOGGED_IN);
      });
    case UserActions.LOAD_USER_FAILURE:
      return initialState;

    default:
      return state;
  }
};

Note that the previous two snippets are not consistent. The previous UserState interface was just an example to show the UserState properties. If you are trying to follow along at this point from the linked example, you may be a little bit confused.

First of all the application does not show an example of this initial implementation not using effects. Secondly, the application uses Immutable.js to create some of the models, which might be a little confusing at first. But if you just keep in mind the properties of the UserState interface mentioned above, it should be pretty easy to still follow along in this article.

In the above reducer, just imagine that the LOAD_USER_SUCCESS action returns the new user state, and the LOAD_USER_FAILED returns the initial default user state. As this article is not mainly about store, these concepts should not be new to you.

Now the last point in the quoted documentation is the state access through Store. For that, we will simply subscribe to the user state in the AppComponent

@Component({
  selector: 'my-app',
  templateUrl: './app.component.html'
})
export class AppComponent {
  user: Observable<User>;

  constructor(private store$: Store<AppState>) {
    this.user = this.store$.let(getUser());
  }
}

You might be used to seeing store$.select('user'), but here, I’m using the selector pattern and just using let. The result is the same. You can find the getUser in the user.selectors file (in the example app).

So now, we have our NgRx components in place, let’s implement the login and see how it would normally be implemented without using Effects.

@Component({
  selector: 'login',
  templateUrl: './login.component.html'
})
export class LoginComponent {

  constructor(private store$: Store<AppState>,
              private userActions: UserActions,
              private authService: AuthService) {}

  login(form: any) {
    this.authService.login({
      username: form.username,
      password: form.password
    })
    .subscribe((res: LoginResponse) => {
      if (res.isError) {
        this.store$.dispatch(this.userActions.loadUserFailure(res.message));
      } else {
        this.store$.dispatch(this.userActions.loadUserSuccess(res.user));
      }
    });
  }
}

As mentioned previously, this example is not in the example application. But you can see from the example, that we just login with the AuthService, and when we get the response, we either dispatch the LOAD_USER_FAILURE action with the error message, or we dispatch the LOAD_USER_SUCCESS action with the logged in user details.

This implementation would be how we would normally do it, without effects; the component (or maybe even the service) would be the one that dispatches the new action to update the user state.

When we introduce effects, what we would do is introduce a new action, that is not necessarily tied directly to any state, like in the case of the two previous user actions. The reason for this, is that the effect will subscribe to this new action, and in a way transform it. Let’s see how the new login implementation will look like

export class LoginComponent {

  constructor(private store$: Store<AppState>,
              private authActions: AuthActions) {}

  login(form: any) {
    this.store$.dispatch(this.authActions.login({
      username: form.username,
      password: form.password
    }));
  }
}

Here, we are introducing a new LOGIN action, that we will put in a new AuthActions class.

export class AuthActions {
  static readonly LOGIN = 'LOGIN';

  login(credentials: Credentials): Action {
    return {
      type: AuthActions.LOGIN,
      payload: { credentials }
    };
  }
}

All the login method does now is dispatch the new LOGIN action, and the effect will subscribe to it, doing most of the legwork that would normally have been handled in the login method. And here is our effects class

@Injectable()
export class AuthEffects {

  constructor(private authService: AuthService,
              private userActions: UserActions,
              private actions$: Actions) {}

  /**
    * On the LOGIN action, this effect will make a request to authenticate.
    * If not authenticated, it will emit a LOAD_USER_FAILURE action.
    * Otherwise, it will emit a LOAD_USER_SUCCESS action.
    */
  @Effect()
  login$ = this.actions$
    .ofType(AuthActions.LOGIN)
    .map(({payload}) => payload.credentials as Credentials)
    .switchMap(credentials => {
      return this.authService.login(credentials)
        .map((res: LoginResponse) => {
          if (res.isError) {
            return this.userActions.loadUserFailure(res.message);
          }
          return this.userActions.loadUserSuccess(res.user);
        });
    });
}

The Actions class is an Effects library API. It is a stream of all the actions dispatched in our application. Here, our effect will subscribe to the LOGIN action. Each LOGIN action will have the credentials as the payload, and we will use Observable.switchMap to make an authentication request, returning a new Observable that will either be mapped to the LOAD_USER_SUCCESS action or the LOAD_USER_FAILED action.

We don’t need to do anything after this (e.g. subscribe to the login$). It is handle transparently. When the LOGIN action is dispatched, the result is like if we had manually dispatched one of the LOAD_USER_XXX actions.

And this is the basis of working with effects. We just dispatch an action that the effect subscribes to, and then the effect should perform some operation(s) and return a different Action observable.

I think one of the main benefits of doing it this way (instead of without effects) is the separation of concerns. This separation makes our components a lot simpler and easier to test. All the components do is subscribe to state and dispatch actions. This makes testing a breeze. No need to make a bunch of crazy mocks like we might normally do. It’s also easier to reason about the side effects when they are all in one location.

And that’s it. It takes a bit of practice to get used to this new way doing things, but in the end, I personally feel like it’s a lot cleaner. I have noticed my tests getting a lot cleaner also.

Angular 2 Testing with Karma and SystemJS

Fri, 16 Dec 2016 00:00:00 -0800

Unit testing is a critical part of any piece of software. Writing tests give us confidence that our individual software components act reliably in accordance to specification. An Angular 2 application is no different. We should write unit tests for our components, services, pipes, directives, etc.

The Angular 2 documentation may be the best source out there for examples (and explanation) of how to write tests for Angular 2 code. There are many examples for many use cases. The one thing that the documentation lacks is an explanation of the configuration of the tests. It only links to a quickstart project, and briefly explains what some of the files are used for. This is great to get started, but if you’re like me, you are curious and want to know how things work.

In this article I will walk through the basics of working with the different technologies used to run the Angular tests (from the linked quickstart), and then go through how they all fit together. There are many different ways we can configure testing with different technologies. The aim of this article is to simply try to demystify the configuration in the Angular 2 Quickstart, by explaining the project’s configuration, step by step.

This is a hands on guide, and to get the most out of it, you should follow along and write the code and understand it, as I explain it. After reading this article, you should be able to create an Angular project from scratch, using SystemJS as the module loader, and Karma as the test runner for your Angular 2 tests.

I will begin by walking through the basics of Karma, then go through the basics of SystemJS. Afterwards, we will add Angular to the project and then configure the test infrastructure to be able to use Angular in the tests. To follow along, you will need to have Node installed and have a text editor ready.

NOTE: The complete source code for this article can be found at GitHub. This project is not meant to be a starter project of any kind. So please do not try to use it as such. Use the quickstart instead. For the best learning experience, this project should only be used as a reference for if you get stuck at any point. It is recommended to write everything yourself.

Getting Started with Karma
- Jasmine Introduction
- Setting up Karma and Running Jasmine Tests
Getting Started with SystemJS
Adding Angular
- Application Setup
- Testing Setup
Summary

Getting Started with Karma

Karma is test runner. What does this mean? Well if you have ever tested any Javascript projects before, you may have used a framework like Mocha or Jasmine. The difference between these two and Karma, is that the frameworks provide the APIs we use in our code to execute tests, while Karma is the one that runs the tests. We could skip Karma and just execute Jasmine or Mocha code in the browser (as it’s just plain Javascript), but Karma allows us to run the test from the command line, allowing us to configure different types of test environments.

Let’s first walk through an example using Jasmine by itself, then we will use Karma to run the Jasmine tests.

Jasmine Introduction

To get started, just create an empty folder, initialize the project with npm and then add the Jasmine dependency.

mkdir angular2-testing
cd angular2-testing
npm init (accept all defaults)
npm install --save-dev jasmine-core lite-server concurrently

lite-server is a just an HTTP server allowing us to run our project on a server (as opposed to just opening the HTML file in the browser). concurrently is just a tool allowing us to run multiple npm commands, as you will see in the scripts we write later.

Let’s also set up TypeScript right now, as our Angular code will be written in TypeScript. So we’ll just get that out of the way right now. All of the code written from here on out, will be written in TypeScript and transpiled to Javascript.

First we need to install TypeScript, and then set up the TypeScript configuration in the tsconfig.json file.

npm install --save-dev typescript core-js @types/node @types/jasmine

We’re also installing the TypeScript typings for jasmine and node as we’ll need them to compile our TypeScript tests.

Then create a tsconfig.json file at the root of the project, and add the following contents

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node",
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "lib": [ "es2015", "dom" ],
    "noImplicitAny": true,
    "suppressImplicitAnyIndexErrors": true
  }
}

I won’t go into anything about this file. You should read the TypeScript documentation for a quickstart guide on getting started with TypeScript, if you are unfamiliar with this.

Let’s now add some scripts to the package.json file, which will allow us to run some basic tasks for our project. Replace the "scripts" property in the package.json with the following:

"scripts": {
  "start": "tsc && concurrently \"tsc -w\" \"lite-server\" ",
  "test": "npm start",
  "tsc": "tsc"
}

The tsc command will simply do a one-time compilation of our TypeScript code. The start command will compile the TypeScript, watch for any changes, and also run the lite-server to serve up our project artifacts. Since we are just using Jasmine by itself for these initial tests, the test command will simply do the same thing as the start command, and will run our tests when we open the index.html page (that we will create in a moment).

Ok, now the set up is complete, we can get to start writing some code.

Create an app folder and inside the app folder, create a counter folder. Now create a counter.spec.ts in the counter folder. In the counter.sepc.ts file, add the following contents:

class Counter {
  _count = 0;

  increment() {
    this._count++;
  }

  decrement() {
    this._count--;
  }

  get value() {
    return this._count;
  }
}

You can see this is just a simple class that increments and decrements the state of the counter. Now directly below that class, add the following

describe('Counter', () => {
  let counter: Counter;

  beforeEach(() => {
    counter = new Counter();
  });

  it('should increase value of counter when incremented', () => {
    expect(counter.value).toEqual(0);
    counter.increment();
    expect(counter.value).toEqual(1);
  });

  it('should decrease value of counter when decremented', () => {
    expect(counter.value).toEqual(0);
    counter.decrement();
    expect(counter.value).toEqual(-1);
  });
});

These are just a couple simple tests to make sure the decrement and increment function work correctly. I won’t get into what the code does. If you have never used Jasmine, please read the documentation.

Also notice that both the Counter class and the tests are in the same file. Normally you would have the Counter class in a separate counter.ts file, and then import it into the test file. But that requires module loading, and we are not there yet in our adventure. This will be explored more in the Getting Started with SystemJS section.

Now let’s compile just to make sure there are no compilation errors. Run

npm run tsc

There should be no errors. You can now see the transpiled .js files right next to the TypeScript .ts file, along with the source map.

Now let’s set up the Jasmine tests. Add an index.html page to the root of the project and add the following contents.

<!doctype html>
<head>
  <meta charset="utf-8">
  <title>Angular 2 Testing</title>

  <link rel="shortcut icon" type="image/png" href="node_modules/jasmine-core/images/jasmine_favicon.png">
  <link rel="stylesheet" href="node_modules/jasmine-core/lib/jasmine-core/jasmine.css">

  <script src="node_modules/jasmine-core/lib/jasmine-core/jasmine.js"></script>
  <script src="node_modules/jasmine-core/lib/jasmine-core/jasmine-html.js"></script>
  <script src="node_modules/jasmine-core/lib/jasmine-core/boot.js"></script>

  <script src="app/counter/counter.spec.js"></script>
</head>
<body>
</body>
</html>

Here, we are adding all the required Jasmine files from the node package we installed earlier. We also add the single spec file we created. I won’t get too much into explaining these files, because using Jasmine this way, is not the point of this article. This is more for those that are coming from a straight Jasmine background. I thought that seeing this would make for an easier transition to Karma.

Now let’s run the test. Simply run npm run test, and the files should compile again. Then the server should start, serving up the index.html page. If all goes well, you should see the Jasmine test results telling you that everything went well. Two tests passed!

Awesome! Now that we’ve seen how to run Jasmine in the browser, let’s set up Karma, and use Karma to run the Jasmine tests.

Setting up Karma and Running Jasmine Tests

Karma Dependencies

First lets install all the required modules to run Karma

karma
karma-cli
karma-jasmine
karma-chrome-launcher
karma-jasmine-html-reporter

Add all of the above to the install command to install them

npm install --save-dev <all-of-the-above>

You should also install the Karma CLI globally.

npm install -g karma-cli

karma and karma-cli are the core Karma module to run Karma. karma-jasmine is the Karma plugin that allows us to run Jasmine tests. Remember that Karma is not dependent on any one testing framework. But most of the time (for Angular projects), you will see the testing framework used is Jasmine.

The xxx-launchers are plugins that correspond to the different browsers you can launch the tests in. For now, we will just use the Chrome launcher, which will start up a Chrome browser to run the tests. But keep in mind that there are also launchers for headless browsers like Chrome.

And finally, the karma-jasmine-html-reporter is the Karma plugin that will allow us to produce jasmine HTML reports, like the one in the previous image.

Now we have the dependencies installed, we need to configure Karma. This is done in a karma.conf.js file.

Karma Configuration

At the root of the project, create a karma.conf.js file and add the following contents into the file.

module.exports = function(config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine'],

    plugins: [
      require('karma-jasmine'),
      require('karma-chrome-launcher'),
      require('karma-jasmine-html-reporter')
    ],

    files: [
      'app/counter/counter.spec.js'
    ],

      reporters: ['progress', 'kjhtml'],

    port: 9876,
    colors: true,
    logLevel: config.LOG_INFO,
    autoWatch: true,
    browsers: ['Chrome'],
    singleRun: false
  });
};

The karma.conf.js is a Node module, and when Karma loads it, it will pass a configuration object. We can use this object to configure Karma by calling the config.set, passing in a configuration object. All of the available configuration properties are listed in the karma documentation. I will quickly go through the ones used above.

basePath - This is the path that Karma will use to resolve files/patterns listed in the files (seen above) array and excludes (not used here) array. In this case we just use '', as we want everything resolved from the root of the project, as seen in the one file listed app/counter/counter.spec.js.
frameworks - As mentioned previously, Karma is not tied to any framework, so here, we are listing Jasmine as the testing framework.
plugins - Here we list the plugins that we installed earlier.
files - Explained in following text.
reporters - the 'kjhtml' reporter uses the karma-jasmine-html-reporter we installed earlier. It allows us to see the Karma HTML result when we run the browser.
The rest should be self explanatory, by the property name. If it is not obvious, please see the documentation.

I wanted to save the files property explanation because it requires a bit of explanation and exploration.

When Karma executes, it starts a web server. All the files include in the files array are the files included in the server. If the file is not listed, then it isn’t added to the server. Let’s give this a test run, for now ignoring any results (which we will get to later). Let’s first add a couple new scripts to the package.json file. In the "scripts" replace the "test" property with the following two

"test": "tsc && concurrently \"tsc -w\" \"karma start karma.conf.js\"",
"test-once": "tsc && karma start karma.conf.js --single-run",

The first one will start the Karma server, and stay running while watching files. The second one will just do a single run. We will use the first one for now. Run the following

npm run test

You should see a Chrome browser launch with something like the following

Now as I mentioned, Karma starts a server and adds the files we listed in the files array. Let’s check it out. Open up a different browser window, and just type into the URL bar

http://localhost:9876/base/app/counter/counter.spec.js

You should see the source code the counter.spec.js file. You may also notice that we used base in the URL. The is important to remember for later, as by default, Karma adds base as the base path. Now try to type in the URL bar

http://localhost:9876/base/app/counter/counter.spec.js.map

The file isn’t found. You should see NOT FOUND in the browser.. Now try to stop the server, add the .map file to the files array, and restart the server. Now try to go to the URL. You should see now see the contents of the .map file. When you’re done, just remove the .map file from the files array.

Let’s now look at another way to add files to files array. Beside from just listing the file as a string, we can also use an object. See the files documentation for all the properties. I will just list three

pattern - This can be a file, or a pattern (using glob pattern matching).
included - Explained below.
watched - Whether Karma should watch this file for changes (and restart if any change is detected).

Lets change the configuration of the files array to:

files: [
  { pattern: 'app/counter/counter.spec.js', included: true, watched: true }
]

This will have the exact same effect as if we were to just use the single string file name. The default for includeed is true, and the default for watched is true. Let’s check out what the included really means. Start Karma again (stop first if needed - configuration changes requires a restart).

npm run test

In the Chrome window, after you see that Karma is connection, open the Chrome developer tools with f12. Now open the “Network” tab and refresh the browser. On the left, in the list of all the files retrieved on the refresh, you should see a context.html page. Click on it to open the contents.

If you look at the right hand side, you will also notice that the counter.spec.js file is added as a <script>. This is what the included means. To run the tests, Karma uses an HTML page to load the scripts into the browser so that the scripts can run.

So why wouldn’t we want the file added as a <script>? Well, when using SystemJS (as we’ll see later) in an application, we don’t add the files as <script>s in the index.html page. SystemJS loads the files dynamically at runtime when the files are needed. So when using SystemJS and Karma, we do the same.

Test Results

So most of the discussion so far has been about configuration. As for the results, there’s really not much to discuss. If you start Karma again, and you look in the terminal, you should see the results at the bottom.

Chrome 54.0.2840 (Windows 10 0.0.0): Executed 2 of 2 SUCCESS (0.295 secs / 0.016 secs)

If you want to view the Jasmine HTML report, click on the Debug button in the Chrome Browser. You should see a similar result as the one earlier.

So that was your introduction to Karma. Next we will explore SystemJS, and then see how we would use it with Karma.

Getting Started with SystemJS

SystemJS is a module loader. So what is a module? From the SystemJS docs:

A module is simply a JavaScript file written with module syntax. Modules export values, which can then be imported by other modules.

Let briefly see what this means in code.

Intro to Modules

Remember our good friend the Counter class, that we just had in the same file as the spec file? Let’s put it into it’s own file, and and the import it into the spec file. Create a counter.ts file in the counter folder, and copy and paste the Counter class (from the spec) into it, also adding the export keyword

export class Counter {
  ...
}

Then in the counter.spec.ts file, remove the Counter class, and instead import it, using the following syntax

import { Counter } from './counter';

Everything else in the spec file should be the same. Now let’s compile both files.

npm run tsc

If you look at the contents of the compiled counter.js file, you should see

var Counter = (function () {
    ...
}());
exports.Counter = Counter;

Here, Counter is being exported with the module. Now look at the counter.spec.js file

var counter_1 = require("./counter");
describe('Counter', function () {
    var counter;
    beforeEach(function () {
        counter = new counter_1.Counter();
    });
});

Using require is how to load the module in Javascript. You can see that the Counter class is actually a member of imported module. That’s why we do new counter_1.Counter() instead of new counter_1().

So how does this fit it with SystemJS. Let’s find out.

SystemJS Quickstart

First, let’s install SystemJS

npm install --save systemjs

Once that’s finished installing, let’s add it to our index.html. If you haven’t already, you can remove all the Jasmine related stuff from the file. (Just a note, in case there is any confusion, none of that Jasmine stuff in the index.html file was actually used in the Karma testing). Replace the contents of the index.html page with the following (removing the (#)s)

<!doctype html>
<head>
  <meta charset="utf-8">
  <title>Angular 2 Testing</title>
  <script src="node_modules/systemjs/dist/system.src.js"></script>  (1)
</head>
<body>
  <h2>Count: <span id="count">0</span></h2>

  <script>
    System.import('app/counter/counter.js').then(function(module) {  (2)
      var counter = new module.Counter();  (3)
      var count = document.getElementById('count');
      setInterval(function () {
        counter.increment();
        count.innerHTML = counter.value;  (4)
      }, 1000);
    });
  </script>
</body>
</html>

There are a few things going on here:

We add the SystemJS script to the application.
We import the counter.js module, using the System.import method. In the promise callback, we get passed an instance of the module.
With the module, we can create an instance of the Counter class.
We change the value of the h2 count every second, with the incremented value of the counter.

Let’s run the code.

npm start

If all went well, you should see the count increment every second. Now let’s take this example to next level.

Importing Modules

Let’s import something from another module into the counter module. I will use RxJS just so we can also see how to use the SystemJS.config. First install RxJS

npm install --save rxjs

Now change the contents of the counter.ts file to

import { BehaviorSubject } from 'rxjs/BehaviorSubject';
import { Observable } from 'rxjs/Observable';

export class Counter {
  
  private _count = 0;
  private _value = new BehaviorSubject<number>(this._count);

  increment() {
    this._value.next(++this._count);
  }

  decrement() {
    this._value.next(--this._count);
  }

  get value(): Observable<number> {
    return this._value.asObservable();
  }
}

Here, we are using RxJS to publish the new value to subscribers. In the index.thml page, change the contents of the <script> accordingly, to adjust to this new change

<script>
  System.import('app/counter/counter.js').then(function(module) {
    var count = document.getElementById('count');
    var counter = new module.Counter();
    counter.value.subscribe(function(value) {
      count.innerHTML = value;
    });
    setInterval(function () {
      counter.increment();
    }, 1000);
  });
</script>

Now lets try to run the app.

npm start

If you look at both the terminal and Browser console, you will see 404 errors. In the browser console, you will see

Uncaught (in promise) Error: (SystemJS) XHR error (404 Not Found) loading
http://localhost:3000/rxjs/BehaviorSubject(…)

What this means is that when the counter module is loaded, it is trying to import the BehaviorSubject. And the error is telling you the path it is trying to load it from. It is using this path, because that is the path we use in our import statement

import { BehaviorSubject } from 'rxjs/BehaviorSubject';

So how can we fix this? This is were the SystemJS.config comes to the rescue. We can configure how different paths are resolved.

Add a systemjs.config.js file to the root of the project, and add the following contents to that file

(function(global) {
  SystemJS.config({
    paths: {
      'npm:': 'node_modules/'
    },
    map: {
      'app': 'app',
      'rxjs': 'npm:rxjs'
    },
    packages: {
      app: {
        defaultExtension: 'js'
      },
      rxjs: {
        defaultExtension: 'js'
      }
    }
  })
})(this);

This is how we can configure SystemJS. The following is a description of the properties used above:

paths - Here we are making an alias so that we can use npm: as an alias for the path node_modules/. This will save us some typing in the map section.
map - Here we are creating mappings, which is also a type of alias. Above, we are saying that when you see rxjs, replace it with the path node_modules/rxjs when resolving the module path.
packages - Here we are saying that for the package rxjs (listed in the map. The default file extension is js. This allows us to exclude the .js from the import.

With this configuration and the following import statement

import { BehaviorSubject } from 'rxjs/BehaviorSubject'

when SystemJS tries to load rxjs/BehaviorSubject, it will now prefix it with node_modules/ and add the default extension .js. Now the path is absolute, and the module can be resolved.

We also add a mapping for app, as this is part of the path for the project files. For this package, we also add the defaultExtension: js. For the code we are using right now in the index.html, this is not really required at this point, as we are importing using the .js extension already. But in the real application, we will not be using extensions with our import statements. And the above mapping will allow for that. So let’s just adjust the index.html page to accommodate for this adjustments. Just change

System.import('app/counter/counter.js')

System.import('app/counter/counter')

See how we removed the .js extension.

Now we just need to add the configuration file the index.html page. Now this is what the <head> should look like

<head>
  <meta charset="utf-8">
  <title>Angular 2 Testing</title>
  <script src="node_modules/systemjs/dist/system.src.js"></script>
  <script src="systemjs.config.js"></script>
</head>

Now we can run the app.

npm start

Voila! Everything now works. You should be feeling like a champ right now! But we still need to test it :-)

Testing with SystemJS

To test our Counter, the first thing we need to do is modify the test cases to accommodate for our new use of RxJS. Replace the contents of the counter.spec.ts file with the following:

import { Counter } from './counter';

describe('Counter', () => {
  let counter: Counter;

  beforeEach(() => {
    counter = new Counter();
  });

  it('should increase value of counter when incremented', (done) => {
    counter.increment();
    counter.value.subscribe(value => {
      expect(value).toEqual(1);
      done();
    });
  });

  it('should decrease value of counter when decremented', (done) => {
    counter.decrement();
    counter.value.subscribe(value => {
      expect(value).toEqual(-1);
      done();
    });
  });
});

Let’s also add the counter.js file to the Karma config so that Karma can add it to the server.

files: [
  { pattern: 'app/counter/counter.js', included: false, watched: true },
  { pattern: 'app/counter/counter.spec.js', included: true, watched: true }
],

Now let’s just run the test as-is, just to see what happens.

npm run test

You should see the following errors (preventing the tests from running):

[1] Chrome 54.0.2840 (Windows 10 0.0.0) ERROR
[1]   Uncaught ReferenceError: require is not defined
[1]   at app/counter/counter.spec.js:2
[1]
[1] Chrome 54.0.2840 (Windows 10 0.0.0) ERROR
[1]   Uncaught ReferenceError: require is not defined
[1]   at app/counter/counter.spec.js:2

So what does this mean? Well let’s look at the compiled counter.js file. At line two we should see

var BehaviorSubject_1 = require("rxjs/BehaviorSubject");

And require is not defined in the Browser engine. So why did it work when we ran the app? It’s because we were using SystemJS to load the module (i.e. we didn’t add the counter.js as a <script>). Also remember when we talked about the Karma configuration files array. Here is what is currently looks like.

files: [
  { pattern: 'app/counter/counter.js', included: false, watched: true },
  { pattern: 'app/counter/counter.spec.js', included: true, watched: true }
],

Remember we said that included means that the file should added as a <script>. Well this is what’s causing the error. For tests, we don’t want our application files added as a <script>. We want SystemJS to load them, just like in the application.

So let’s update the files array:

files: [
  'node_modules/systemjs/dist/system.src.js',

  { pattern: 'node_modules/rxjs/**/*.js', included: false, watched: false },
  { pattern: 'node_modules/rxjs/**/*.js.map', included: false, watched: false },

  { pattern: 'systemjs.config.js', included: false, watched: false },
  { pattern: 'app/counter/counter.js', included: false, watched: true },
  { pattern: 'app/counter/counter.spec.js', included: false, watched: true }
],

So we are now adding SystemJS. Also just using a string for the module (instead of the object like the other three files used), we accept the defaults, which is included: true, watched: false. We do want SystemJS added as a <script> and we don’t need to watch it, as it’s a third-party library, and the code will not be changing. We also add our systemjs.config.js file. We are not including it as a <script> as we will have SystemJS load it. And finally, we added the RxJS library.

At this point, if we tried to run the test, nothing would happen, i.e. no tests would be run. This is because 1) The spec file is not added as a <script> and 2) we haven’t told SystemJS to load them yet.

This is where we want to make use of a karma-test-shim.js file, that we can use just for tests. In this file, we will have SystemJS load all of our modules.

karma-test-shim.js

Create a karma-test-shim.js file at the root of the project. As I mentioned before, this article is to help demystify the workings of the Angular 2 Quickstart project (in regards to testing). So I will grab some of the content from its karma-test-shim.js. I won’t grab all of it right now, as a lot it involves Angular, and I haven’t gotten there yet. I will just grab what is important for now and briefly walk through what all the code does. So in your file, add the following contents:

Error.stackTraceLimit = 0;
jasmine.DEFAULT_TIMEOUT_INTERVAL = 1000;

// (1)
var builtPaths = (__karma__.config.builtPaths || ['app/'])
                  .map(function(p) { return '/base/'+p;});

// (2)
__karma__.loaded = function () { };

// (3)
function isJsFile(path) {
  return path.slice(-3) == '.js';
}

// (4)
function isSpecFile(path) {
  return /\.spec\.(.*\.)?js$/.test(path);
}

// (5)
function isBuiltFile(path) {
  return isJsFile(path) &&
          builtPaths.reduce(function(keep, bp) {
            return keep || (path.substr(0, bp.length) === bp);
          }, false);
}

// (6)
var allSpecFiles = Object.keys(window.__karma__.files)
  .filter(isSpecFile)
  .filter(isBuiltFile);

// (7)
SystemJS.config({
  baseURL: 'base'
});

// (8)
System.import('systemjs.config.js')
  .then(initTesting);

// (9)
function initTesting () {
  return Promise.all(
    allSpecFiles.map(function (moduleName) {
      return System.import(moduleName);
    })
  )
  .then(__karma__.start, __karma__.error);
}

It looks like there is alot going on here, but really, most of the code is just helper functions. I’ll quickly go through them

First couple lines - Not really important right now. Just some environment settings.
(2) - Here we are using this hook to tell Karma not to start the tests. We will manually trigger the tests after SystemJS has loaded all the modules.
(6) - This is our main goal: to get all the .spec files. We only want .spec files that are a part of our application. The helper functions (3), (4), and (5) help us filter all the files to make sure we get what we want.

The Object.keys(window.__karma__.files) grabs all the files in our Karma config files array, and then we use the helper functions to filter them out.

We only want the .spec files because that all we want SystemJS to load. The spec files already import the application files, so we don’t need to import them manually. They will be imported transitively when SystemJS sees the requires.
(7) - Here we are setting the baseURL in the SystemJS configuration. Remember that Karma adds the base path base to the webserver URL. So SystemJS will use the same base URL when trying to load modules.
(8) - We now load the systemjs.config.js file, and when that module is resolved, we call (9)
(9) - Here, we use the helper function (that grabbed all the spec files), we iterate through them, importing all of them with System.import. After they are all resolved, we manually start Karma by passing the karma start function to the Promise then.

Now the last thing is to add this karma-test-shim.js file to the karma.conf.js file, so that Karma can load it and add it as a <script> to run when the server starts. Below is the current files array configuration.

files: [
  'node_modules/systemjs/dist/system.src.js',

  { pattern: 'node_modules/rxjs/**/*.js', included: false, watched: false },
  { pattern: 'node_modules/rxjs/**/*.js.map', included: false, watched: false },

  { pattern: 'systemjs.config.js', included: false, watched: false },
  'karma-test-shim.js',

  { pattern: 'app/counter/counter.js', included: false, watched: true },
  { pattern: 'app/counter/counter.spec.js', included: false, watched: true }
],

Now if you run the test (npm run test), you should get a success with 2 tests run and 2 tests succeeding!

Bet you feel pretty good about yourself right about now. Do you feel like a Guru yet? Not so fast, Grasshopper. We still need to add Angular!

Adding Angular

Finally, we’ve reached the point where we can now add Angular to our project.

Application Setup

Let’s start by first just adding the dependencies, getting a hello world up and running, then we’ll get the testing. So install the following

npm install --save \
  @angular/core @angular/common @angular/compiler \
  @angular/platform-browser @angular/platform-browser-dynamic \
  core-js reflect-metadata zone.js

These are just the basic dependencies. We’re not going to do any forms or http calls or routing, so we’ll just leave those out.

Now let’s code up the application. In the app folder, add the following files:

app.component.ts

import { Component } from '@angular/core';

@Component({
  selector: 'app',
  template: '<h1></h1>'
})
export class AppComponent {
  message = 'Hello World!';
}

main.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppComponent } from './app.component';

@NgModule({
  imports: [ BrowserModule ],
  declarations: [ AppComponent ],
  bootstrap: [ AppComponent ]
})
export class AppModule {

platformBrowserDynamic().bootstrapModule(AppModule);

And replace the contents of the index.html file with the following:

<!DOCTYPE html>
<html>
  <head>
    <title>Angular2 Testing</title>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="node_modules/core-js/client/shim.min.js"></script>
    <script src="node_modules/zone.js/dist/zone.js"></script>
    <script src="node_modules/reflect-metadata/Reflect.js"></script>
    <script src="node_modules/systemjs/dist/system.src.js"></script>
    <script src="systemjs.config.js"></script>
    <script>
      System.import('app').catch(function(err){ console.error(err); });
    </script>
  </head>

  <body>
    <app>Loading ...</app>
  </body>
</html>

You can see here, that we use System.import to import the app package. But we need to make one change to the systemjs.config.js file. Add a main property that points our compiled main.js.

app: {
  main: './main.js',
  defaultExtension: 'js'
}

The main tells SystemJS what file is the main file to load for this (app) package. In this case, the main.js file is the default one to load. And when that file is loaded, it will bootstrap our Angular application.

We also need to make SystemJS aware of how to load the Angular modules. In our application files, when we import Angular, we do something like

import { Component } from '@angular/core';

SystemJS doesn’t know what the @angular/core module is unless we map it correctly in the systemjs.config.js file, just like we did with RxJS. So modify the map property in the systemjs.config.js file to the following:

map: {
  'app': 'app',

  '@angular/core': 'npm:@angular/core/bundles/core.umd.js',
  '@angular/common': 'npm:@angular/common/bundles/common.umd.js',
  '@angular/compiler': 'npm:@angular/compiler/bundles/compiler.umd.js',
  '@angular/platform-browser': 'npm:@angular/platform-browser/bundles/platform-browser.umd.js',
  '@angular/platform-browser-dynamic': 'npm:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js',

  'rxjs': 'npm:rxjs'
}

See how we are mapping the @angular/core to the actual module file. This is how we are able to to use from '@angular/core'.

At this point, running the app should work. Give it a shot.

npm start

You should see the “Hello World!” message. And now we have Angular set up for the application. But we still need to configure the testing.

Testing Setup

Let’s start with the karma.conf.js file. In the files array, add the following right under the systemjs.src.js file

// Polyfills
'node_modules/core-js/client/shim.js',
'node_modules/reflect-metadata/Reflect.js',

// zone.js
'node_modules/zone.js/dist/zone.js',
'node_modules/zone.js/dist/long-stack-trace-zone.js',
'node_modules/zone.js/dist/proxy.js',
'node_modules/zone.js/dist/sync-test.js',
'node_modules/zone.js/dist/jasmine-patch.js',
'node_modules/zone.js/dist/async-test.js',
'node_modules/zone.js/dist/fake-async-test.js',

I won’t really get into what all these files are. Just accept that they are needed when testing Angular applications. And just notice that because we are just using strings, all these files are added as <script>s.

Next we will add the Angular files. So right under the above files, add the following

{ pattern: 'node_modules/@angular/**/*.js', included: false, watched: false },
{ pattern: 'node_modules/@angular/**/*.js.map', included: false, watched: false },

Here we are using a pattern matcher instead of individual files. This will match all the files in the @angular/xxx modules. We also add the source maps so that they can be used for debugging (we won’t do any debugging here). Also notice that we use included: false, which means that they will not get added as <script>s. They will get loaded by SystemJS.

Now we need to add our application files. Previously, with the counter files, we added them individually. Let’s change that to use a pattern to add all of our files, just like we did with the Angular files. So replace the following

{ pattern: 'app/counter/counter.js', included: false, watched: true },
{ pattern: 'app/counter/counter.spec.js', included: false, watched: true }

with

{ pattern: 'app/**/*.js', included: false, watched: true },
{ pattern: 'app/**/*.ts', included: false, watched: true },
{ pattern: 'app/**/*.js.map', included: false, watched: true }

we are also adding the source maps and the source .ts files here for debugging. But again, we will not be doing any debugging here. And again, notice the included: false. We will also let SystemJS load these modules.

And that is it for the Karma configuration (for now). Now we need to tell SystemJS to load the files. So let’s go to our karma-test-shim.js file.

Remember that in this file, we are loading the systemjs.config.js file with a System.import. Remember the systemjs.config.js file has all the mapping for the Angular files so we can do from @angular/core. In our tests, we are also now using the Angular testing files, which are not mapped in the systemjs.config.js. We don’t map them there because they are specific to testing, and we don’t want to clutter our application stuff with unnecessary testing stuff.

In our tests will will being using things like

import { TestBed } from '@angular/core/testing'

All of these @angular/xxx/testing modules, we still need to map. So change the SystemJS.config ((7) previously mentioned) in the karma-test-shim.js to the following

System.config({
  baseURL: 'base',

  map: {
    '@angular/core/testing': 'npm:@angular/core/bundles/core-testing.umd.js',
    '@angular/common/testing': 'npm:@angular/common/bundles/common-testing.umd.js',
    '@angular/compiler/testing': 'npm:@angular/compiler/bundles/compiler-testing.umd.js',
    '@angular/platform-browser/testing': 'npm:@angular/platform-browser/bundles/platform-browser-testing.umd.js',
    '@angular/platform-browser-dynamic/testing': 'npm:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic-testing.umd.js',
  },
});

This is just like the mapping in the systemjs.config.js file, except now, we are adding the testing modules.

We’re still not done with the configuration yet, but let’s try testing out what we have so far. We will get an error, but I want to be able to show what the problem is, and how we can fix it. So let’s add a test. Add a file name app.component.spec.ts in the app folder, and add the following contents:

import { TestBed, ComponentFixture } from '@angular/core/testing';
import { AppComponent } from './app.component';

describe('component: AppComponent', () => {
  let fixture: ComponentFixture<AppComponent>;

  beforeEach(() => {
    TestBed.configureTestingModule({
      declarations: [ AppComponent ]
    });
    fixture = TestBed.createComponent(AppComponent);
    fixture.detectChanges();
  });

  it('should display Hello World message', () => {
    const debugEl = fixture.debugElement;
    const h1 = debugEl.nativeElement.querySelector('h1');
    expect(h1.textContent).toEqual('Hello World!');
  });
});

I’m not going to get into what this code does. That is not the purpose of this article. Angular documentation has great info on this subject.

Let’s now run the test.

npm run test

When running the test, we should see one failure, which is from the app.component.spec file we just added. The error reads:

[1]     TypeError: Cannot read property 'injector' of null

The reason for this, is that when using the TestBed, it needs to be initialized in a special way. Let’s quickly see how to do that. In the same spec file, add the following imports:

import {
  BrowserDynamicTestingModule, platformBrowserDynamicTesting
} from '@angular/platform-browser-dynamic/testing';

Then in a beforeAll, right before the beforeEach, add the following:

beforeAll(() => {
  TestBed.initTestEnvironment(
    BrowserDynamicTestingModule,
    platformBrowserDynamicTesting()
  );
});

If you run the tests again (or just watch it reload from the previous start), it should produce successes for all cases.

The thing about the TestBed.initTestEnvironment is that it only needs to be called once for the entire test environment. So what we do instead of trying to add it to a test file like we did here, we instead call it in the karma-test-shim.js file. So remove the contents of the last step we just did (the import and the beforeAll). Then in the karma-test-shim.js file, replace

System.import('systemjs.config.js')
  .then(initTesting);

with

System.import('systemjs.config.js')
  .then(initTestBed)
  .then(initTesting);

function initTestBed(){
  return Promise.all([
    System.import('@angular/core/testing'),
    System.import('@angular/platform-browser-dynamic/testing')
  ])

  .then(function (providers) {
    var coreTesting    = providers[0];
    var browserTesting = providers[1];

    coreTesting.TestBed.initTestEnvironment(
      browserTesting.BrowserDynamicTestingModule,
      browserTesting.platformBrowserDynamicTesting());
  })
}

What we are doing in the initTestBed function is loading the two Angular testing modules, the ones that contain the TestBed, and the other two imports we used just recently. When those two modules are resolved, we call the TestBed.initTestEnvironment with the same two arguments as we did previously.

Now if you run the tests again (or just wait for reload) the tests should again pass!

And there you have it. You have now graduated from Grasshopper to Guru.

One last thing I should probably add though, that I didn’t mention previously. That is how to deal with Angular retrieved assets, like our external templates and styles. For these you will need to add the files to the Karma config files array.

{ pattern: appBase + '**/*.html', included: false, watched: true },
{ pattern: appBase + '**/*.css', included: false, watched: true },

Then, right below the files array property, add the following

proxies: {
  "/app/": "/base/app/"
},

There are some comments in the quickstart, that explain what these are for. I won’t really go through it.

Summary

We’ve gone through a lot in this article. First we examined testing with Jasmine in the browser. Then we switched over to Karma, and saw how it can be used to run Jasmine tests from the command line. After that, we got familiarized with SystemJS, using our Counter class along with RxJS. We then tested the Counter code, configuring SystemJS into the Karma configuration. Angular 2 was then added to the mix, and we saw what we need to do to configure Karma to be able to use the Angular modules.

Working with Jersey Configuration Properties

Sun, 27 Dec 2015 00:00:00 -0800

Often in a Jersey application, you need configuration properties that need to be applied dynamically. In this article I will describe some native capabilities in Jersey, how we can extend that native capability into make injectable properties, and finally I will explain how to use a small module I created for working with properties.

Native Capabilities
Custom Injection of Properties
jersey-properties Module

Native Capabilities

JAX-RS contains a class javax.ws.rs.core.Configuration from which we can obtain arbitrary properties from, that can be compiled from different locations. With Jersey, these properties can come from either servlet init-params or from explicitly set properties from a ResourceConfig or Application subclass. In a ResourceConfig, we could just call the property(key, value) method. For example

public class AppConfig extends ResourceConfig {
    public AppConfig() {
        property(PROP_KEY, PROP_VALUE);
    }
}

Or in an Application (only JAX-RS 2.0) subclass

public MyApplication extends Application {
    @Override
    public Map<String, Object> getProperties() {
        Map<String, Object> props = new HashMap<>(); 
        props.put(PROP_KEY, PROP_VALUE);
        return props;
    }
}

Either way, there are a countless number of ways you could populate the configuration properties. For instance you can read a .properties file, and fill the properties with the contents of the Properties object.

Once you’ve registered your properties, you can inject the above mentioned Configuration instance into your resource classes or providers. For example

@Path("config")
public class ConfigResource {
    
    @Context
    private Configuration configuration;
    
    @GET
    public String getConfigProp() {
        return (String)configuration.getProperty(CONFIG_PROP);
    }
}

You can see a complete test case of the above example in this GitHub Gist

Custom Injection of Properties

What if we want to avoid having to repetitively get the property from the Configuration object? Say we want to just inject the property value, maybe with a custom annotation. That is possible with the use of an (HK2) InjectionResolver. For example you can do something like

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public static @interface Config {
    String value();
}

public class ConfigInjectionResolver implements InjectionResolver<Config> {
    
    @Context
    private Configuration configuration;

    @Override
    public Object resolve(Injectee injectee, ServiceHandle<?> handle) {
        if (String.class == injectee.getRequiredType()) {
            Config annotation = injectee.getParent().getAnnotation(Config.class);
            if (annotation != null) {
                String prop = annotation.value();
                return (String)configuration.getProperty(prop);
            }
        }
        return null;
    }
    ...
}

Then register the InjectionResolver with HK2

ResourceConfig config = new ResourceConfig();
config.register(new AbstractBinder(){
    @Override
    protected void configure() {
        bind(ConfigInjectionResolver.class)
                .to(new TypeLiteral<InjectionResolver<Config>>(){})
                .in(Singleton.class);
    }
});

This will now allow us to inject the property as a String value into our resource class or provider.

@Path("config")
public class ConfigResource {
    
    @Config(PROP_KEY)
    private String propValue;
    
    @GET
    public String getConfigProp() {
        return propValue;
    }
}

You can see a complete runnable test case at this GitHub Gist.

One limitation of the above implementation is that it doesn’t allow for method parameter injection. This is not so much that there is anything wrong with the implementation, it is about the way the Jersey handles parameter injection. To read more about it, see Custom Method Parameter Injection in Jersey 2. Usually though, there is not much need to inject configuration properties into method parameters.

Note: Another thing about the above InjectionResolver implementation is that it does not support constructor injection. To see a complete example that does support this, see this Stack Overflow post.

jersey-properties Module

I created a small module that helps with working with configuration properties. You can find the project at GitHub, where there you can read more about about it. To use it you need to add this Maven artifact

<dependency>
    <groupId>com.github.psamsotha</groupId>
    <artifactId>jersey-properties</artifactId>
    <version>0.1.1</version>
<dependency>

To use it at it’s most basic form, you should register the JerseyPropertiesFeature, along with specifying a properties file from where it can obtain the properties.

public class AppConfig extends ResourceConfig {

    public AppConfig() {
        register(JerseyPropertiesFeature.class);
        property(JerseyPropertiesFeature.RESOURCE_PATH, "app.properties");
    }
}

With this basic configuration, if your app.properties contained the following

some.prop=Some value

you would be able to do any of the following injections

@Path("test")
public class SomeResource {

    @Prop("some.prop")
    private String someFieldProp;

    private String someConstructorProp;

    public SomeResource(@Prop("some.prop") String someConstructorProp) {
        this.someConstructorProp = someConstructorProp;
    }

    @GET
    public String get(@Prop("some.prop") String someParamProp) {
        return someParamProp;
    }
}

Aside from this basic set up, you can also implement a PropertiesProvider, that can be registered, and this where the properties would come from.

public class MorePropertiesProvider implements PropertiesProvider {

    private final Map<String, String> moreProps = new HashMap<String, String>();

    public MorePropertiesProvider() {
        moreProps.put(PROP_ONE_KEY, PROP_ONE_VALUE);
    }

    @Override
    public Map<String, String> getProperties() {
        return moreProps;
    }
}

Then just register the provider in the JerseyPropertiesFeature

public AppConfig() {
    register(JerseyPropertiesFeature(new MorePropertiesProvider());
    property(JerseyPropertiesFeature.RESOURCE_PATH, "app.properties");
}

With the PropertiesProvider, you are able to easily extend this feature to get property from some other way, say from a yaml file.

To read more about this module, please read the README in the GitHub project, linked above. Also check out the tests in the project for some other use cases.

Request Scoped Injection into a Singleton with Jersey

Wed, 16 Dec 2015 00:00:00 -0800

I had a problem recently where I was trying to inject a request scoped service into a singleton object. This article will briefly go through my findings.

Say for instance you have something like

@Provider
public class SomeFilter implements ContainerRequestFilter {
    
    @Inject
    private RequestScopedService service;
}

public class AppBinder extends AbstractBinder {
    @Override
    protected void configure() {
        bindFactory(RequestScopedServiceFactory.class)
                .to(RequestScopedService.class)
                .in(RequestScoped.class);
    }
}

The problem with this is that SomeFilter is created on startup, and there is only one single instance for the entire application. So the injection fails, as it should, as there is no request and so no request to bind the request scoped service to. So the application doesn’t start.

My normal fix would have need to inject the service as a javax.inject.Provider<T> instead. This allows me to lazily retrieve the service, which will actually be a proxy.

@Provider
public class SomeFilter implements ContainerRequestFilter {
    
    @Inject
    private javax.inject.Provider<RequestScopedService> serviceProvider;

      @Override
      public void filter(ContainerRequestContext context) {
          RequestScopedService serivce = serviceProvider.get();
      }
}

But I don’t like this. It may be fine for my application, but my problem actually involved creating a framework feature, where I wanted the user to be able to inject the service transparently, without the need to have to worry about scopes, javax.inject.Providers, and such.

Now have a look at this

@Provider
public class SomeFilter implements ContainerRequestFilter {
    
      @Context
      private HttpServletRequest request; 

      @Context
      private UriInfo uriInfo;
 
      @Context
      private SecurityContext securityContext;
}

All three of those injected objects are inherently request scoped, but this doesn’t fail on start up. Everything works fine as expected. So how does it work? It works through the use of Java’s dynamic proxies. If you are unfamiliar with the concept, this article should help get you up to speed.

With dynamic proxies, you are not actually working with the injected instance, but actually a proxy wrapping access to the current request scoped instance. If you print out/log any of the above injected objects’ class names, you will see the it is actually an instance of com.sun.proxy.ProxyX, rather than an instance of the actual advertised types.

In order for the framework to inject a proxy, we need to make sure the type is proxiable. With HK2, this is simple. We do not need to create our own proxy or create an InvocationHandlers. It is simply a matter of making a one or to chained method calls in our binding of the RequestScopedService

@Override
protected void configure() {
    bindFactory(RequestScopedServiceFactory.class)
            .proxy(true)
            .proxyForSameScope(false)
            .to(RequestScopedService.class)
            .in(RequestScoped.class);
}

The proxy method makes the object proxiable. That is the least we need to make this work. With just that one method call, we get dynamic proxies for free, and the injection should now work. The second call to proxyForSameScope is set to false. This means that if an object, say a resource object is in the same request scope, the actual instance should be injected instead of the proxy. This is actually how the three objects injected above works also. You will see that in a request scope, they are the actual objects, but in singletons, they are proxies.

A complete example can be found in this Gist

Bonus (Warning!)

One thing I discovered while testing things out is that when using @Singleton on a resource class, you would expect the request scoped injection (without proxying) to fail on start up, as it would trying to inject into the filter

@Singleton
@Path("resource")
public class SingletonResource {

    @Inject
    private RequestScopedService service;
}

But surprisingly, this does not fail. But what’s worse is that it is injected only once. What you were expecting to change per request will stay the same. The reason is that @Singleton resources are not created until the first request. So there actually is a request scope during injection. So any request sensitive information is injected with the service only once. Now all subsequent request will see all the first request’s context sensitive information.

Yes, I think this is a huge bug. I will probably file JIRA issue. But in the mean time, I strongly suggest staying away from the @Singleton annotation. If you want a singleton, just register the instance in your ResourceConfig

public class AppConfig extends ResourceConfig {
    public AppConfig() {
        register(new SingletonResource());
    }
}

On start up, Jersey will try to inject the resource, and will fail as expected, as there is not request scope.

Dynamic Proxies and Dependency Injection

Wed, 16 Dec 2015 00:00:00 -0800

In this article, I will discuss how dynamic proxies work in the Java platform and how dependency injection takes advantage of this Java feature. This writing is derived from my search to try and inject request scope objects into singleton objects, within the HK2 framework (or more precisely, HK2 within a Jersey application). I was going to include my findings all into one blog, but I felt this topic is too broad for a problem that is solved in two lines of code.

First, I will go through a quick discussion about the Proxy Pattern, then show how to use dynamic proxies with the Java language, then finally go through an example using dynamic proxies and custom dependency injection.

Proxy Pattern

I won’t get into too much detail about the proxy pattern. There is good reading all over the internet. I will just give a brief analogy, along with some brief code example of the pattern.

I’m sure most of you have heard the phrase “vote by proxy”. It’s when someone places a vote for someone else. For example say there is some arbitrary vote among board members of a corporation. Member B is sick in the hospital, so can’t attend the board meeting. So member B signs over a proxy vote to member A. So during the vote meeting, member A places member B’s vote for them. Member A is just acting as a delegate for member B.

The proxy pattern works the same. Here is a class diagram (from wikipedia).

Say Member is the interface

public interface Member {
   void vote();
}

Then you have MemberA and MemberB

public class MemberA implements Member {
    public void vote() {}
}

public class MemberB implements Member {
    public void vote() {}
}

Since member B will not be present, we need a proxy for it. The proxy should also implement the Member interface and it should hold a reference to MemberB.

public class MemberBProxy implements Member {
    private MemberB memberB;

    public void vote {
        memberB.vote();
    }
}

So now MemberA can get a the member B proxy and make the proxy vote for member B.

This might not be the greatest example, as the proxy does nothing but call the vote on member B. But with real proxies, there is usually something else going on under the hood. For example in the case of remote proxies, the vote() method might actually make a network call to a remote MemberB. An example of this in the Java platform, would be RMI (remote method invocation). The example later will describe another use case, that is usually handled transparently for the developer.

Dynamic Proxies

With the example above, we had to manually write the proxy class. In Java though, this is not required, with the introduction of dynamic proxies in 1.3. The core interface to dynamic proxies is java.lang.reflect.Proxy. To use it, we require to components, our interface to proxy, and an InvocationHandler. Let’s look at a quick example, using the same above analogy.

Member memberBProxy = (Memeber) Proxy.newProxyInstance(
        Memeber.class.getClassLoader(),
        new Class[] { Member.class },
        new InvocationHandler() {
            @Override
            public Object invoke(Object proxy, Method method, Object[] args) {
                return method.invoke(new MemberB(), args);
            }
        }
);

That’s it. Now memberBProxy is a Proxy instance, not a MemberB instance. If you print out the class name of the Member object, you will actually see that the class name is com.sun.proxy.ProxyX, and not MemberB.

Let’s walk through it real quick. Here’s is the signature for Proxy#newProxyInstance

newProxyInstance(ClassLoader loader, Class<?>[] interfaces, InvocationHandler h)

It first requires the ClassLoader for which to define proxy. Second it requires to interfaces to implements, then finally the InvocationHandler. The InvocationHandler has only a single callback method we need to implement

Object invoke(Object proxy, Method method, Object[] args)

The first argument is the actual proxy object. You should rarely have use for this. The second argument is the java.lang.reflect.Method. If you’ve had any experience with Java reflection, you should be familiar with the interface. With the Method, we can invoke a method call by passing the object for which to invoke the method on, along with any arguments, hence the last line

return method.invoke(new MemberB(), args);

Here the proxy hands the Method and the arguments passed to the method call on the proxy. We as the InvocationHandler implementer, can do whatever we want with the Method and method arguments. Here we are simply say that the called method should be invoked in the new MemberB() object, passing in the arguments.

To get a clearer picture, just look at it like the Proxy instance has all the methods the Member interface has. So when we call Proxy#vote(), it calls the InvocationHandler#invoke passing in itself, the Method, and the arguments passed to vote() (if any). And out InvocationHandler implementation simply call the method, by calling inovoke on the Method object. the Method object then invokes the vote() on the actual MemberB object.

And that’s it. As you can see, dynamic proxies are fairly simple to implements.

Dynamic Proxy and Custom Injection Example

Get the GitHub project

What I will attempt to do here is try to explain how dynamic proxies are used in a dependency injection framework. One of the main use cases for dynamic proxies within DI, is when dealing with scopes. For instance you have a service or a controller that is in a singleton scope, meaning that there is only one create per application. That singleton service is dependent on a server this is in a request scope, meaning that one should be created for each request. The classes might look something like (it’s all imaginary - no specific framework).

@Controller(scope = "singleton")
public class AppController {
    @Inject
    SingletonService service;
}

@Singleton
public class SingletonService {
    @Inject
    RequestScopedService service;
}

@RequestScoped
public class RequestScopedService {}

The problem here is that when the SingletonService is created on start-up, all the injections need to be performed. But there is no request on start-up, so there should be no RequestScopedService currently tied to a request. Another problem is how do we managed which request gets which RequestScopedService. Maybe we can add a setter in the SingletonService where we can set a new RequestScopedService for each request. But that doesn’t work, because the SingletonService will be accessed concurrently, as is how some servers work (a thread per request).

This is where dynamic proxies come to the rescue. When the SingletonService is created on start up, instead of injection an actual RequestScopedService, we will inject a Proxy of the service. When calls are made on the RequestScopedService from inside the SingletonService, the call will actually be made on the Proxy, which will delegate the call to the InvocationHandler#invoke method, which we will implement to call a RequestScopedService that we obtain from a ThreadLocal. A new RequestScopedService will be set in the ThreadLocal every time a request is processed, which will be handled in a separate thread. If you have ever heard the term “thread local proxy”, this is pretty much the gist of how it works.

So let’s try and implement all this. We will even implement our own dependency injection. We will implement a simple server framework, that allows a user to implement a custom RequestHandler that can inject our SingletonService which will in turn be dependent on a RequestScopedService. Here is the class diagram. (To follow along, it’s best to grab the GitHub project from the above link).

As stated earlier, the user will be able to implement a custom RequestHandler and inject our SingletonService. In the project, there is default implementation that just returns the message from the SingletonService, as a Response

public class DefaultRequestHandler implements RequestHandler {
    
    @Inject
    private SingletonService singletonService;

    @Override
    public Response handleRequest(Request request) {
        return new Response(singletonService.getMessage());
    }  
}

Then the user creates the Server passing the implementation class to the constructor

Server server = new Server(DefaultRequestHandler.class);

In the server constructor, you will see a couple things, the validation of the user defined RequestHandler class, and the creation of the SingletonService. Validation is not important here, and here is the creation of the SingletonService.

private static SingletonService initSingletonService() {
    Service proxyService = (Service) Proxy.newProxyInstance(
            Service.class.getClassLoader(), new Class[]{Service.class},
            new ServiceInvocationHandler());
    return new SingletonService(proxyService);
}

The first thing we do is create the proxy of the Service class. Here is the ServiceInvocationHandler

public class ServiceInvocationHandler implements InvocationHandler {

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) .. {
        Service service = ThreadLocalService.get();
        return method.invoke(service, args);
    }
}

It doesn’t do much. It just retrieves the Service from the ThreadLocalService, and invokes the proxied method on the service. We will see a bit later when the instance of the RequestScopedService is set into the ThreadLocal.

Then the SingletonService is created with the proxy Service. So now, when SingletonService calls a method on the Service, the proxy will lookup the thread local Service and delegate the call to its methods.

That’s it for the server bootstrap. Now we can get into the runtime and request processing. Here is the sequence diagram from the request processing flow.

First the Main program calls Server#sendRequest(Request) passing in a new Request object. A Request object has nothing more than the name of the client.

when we call sendRequest on the Server, all it does it add the Request to the BlockingQueue.

public void sendRequest(Request request) {
    try {
        requests.put(request);
    } catch (InterruptedException ex) {
        throw new RuntimeException(ex);
    }
}

When the server is started, it constantly polls the BlockingQueue, waiting for a new Request

public void startServer() {
    executors.submit(new Runnable() {
        @Override
        public void run() {
            while (true) {
                try {
                    Request request = requests.take();
                    if (request.isShutdownTrigger()) {
                        break;
                    }
                    executors.submit(new RequestProcessor(userDefineHandler,
                                                          singletonService,
                                                          request));
                } catch (InterruptedException ex) {
                    throw new RuntimeException(ex);
                }
            }
            System.out.println("Server shutdown!");
        }
    });  
}

When a Request is received, the Server creates a new RequestProcessor, passing in the Request object, the SingletonService object, and the use defined RequestHandler class. If you look at the run() method of the RequestProcessor, you will see the following

private void setThreadLocalService() {
    ThreadLocalService.set(new RequestScopedService(request));
}

@Override
public void run() {
    setThreadLocalService();
    RequestHandler handler = initInjections();
    Response response = handler.handleRequest(request);
    System.out.println(response.getMessage());
}

So the first thing the processor does is set the RequestScopedService into the ThreadLocalService. Then the RequestHandler is instantiated, using some reflection, as seen in the initInjections() method

RequestHandler initInjections() {
    try {
        for (Field field : handlerCls.getDeclaredFields()) {
            if (field.isAnnotationPresent(Inject.class)
                    && field.getType() == SingletonService.class) {
                return createHandler(field, handlerCls);
            }
        }

        Constructor[] cons = handlerCls.getConstructors();
        for (Constructor con : cons) {
            if (con.isAnnotationPresent(Inject.class)
                    && con.getParameterCount() == 1
                    && con.getParameterTypes()[0] == SingletonService.class) {
                return (RequestHandler) con.newInstance(singletonService);
            }
        }
    } catch (Exception ex) {
        throw new RuntimeException(ex);
    }
    throw new RuntimeException("RequestHandler could not be created.");
}

The method simply checks to see if we should be doing field injection or constructor injection. It makes sure the field or constructor in annotated with @Inject. If the field is annotated, and the field type is SingletonService, we will set the field with the SingletonService, using reflection. Similar events occur to process constructor injection.

The last thing the RequestHander does is simply call the handleRequestof the RequestHandler, which returns a Response, then the processor prints the Response message. And that’s it for the processing of a single request.

If you run the Main class, you should see something similar to the following

Message: Hello Kobe
  meta-info:
    service class: com.sun.proxy.$Proxy2
    service id: 1
    thread name: pool-1-thread-2

Message: Hello Lebron
  meta-info:
    service class: com.sun.proxy.$Proxy2
    service id: 2
    thread name: pool-1-thread-3

... three more

The first thing that you should notice is that the service class is indeed the Proxy instance, and not the RequestScopedService. The underlying will RequestScopedService will remain the same as long as the request is being processed. So all made on the Service inside the SingletonService will always be delegated to actual RequestScopedService associated with a particular thread.

And that’s it.

Summary

We covered some basics on the Proxy Pattern, and saw how it uses a wrapper or delegation model to make calls to an underlying object. Then we covered dynamic proxies, and how it is implemented in the Java language. The finally we went through an example of how dynamic proxies work with scoped dependency injection. If an object in a lesser scope needs to be injected in to an object in a wider scope, the lesser scope object needs to be proxied, so that different thread have access to their own lesser scoped object instance.

The example is far from some thing you’d use in real life, but I hope it gives you a better understanding of what goes on under the hood with regards to the combination of the two subject matters we discussed, dynamic proxies and dependency injection.

Custom Method Parameter Injection with Jersey

Sun, 01 Nov 2015 00:00:00 -0700

In this article I will explain how to handle custom method parameter injection with Jersey 2. I will first go through some “non-custom” injections that work, then go through some custom injections that don’t work, then finally go through how to make them work.

This article assumes you have some working knowledge of dependency injection with Jersey, which is handle by it’s underlying DI framework HK2. if you don’t have any experience, you can still follow along, but it would probably make more sense to you if you first go through Custom Injection and Lifecycle Management from the Jersey user guide.

Let’s start off with an example. I will use the concept of a tenant in the example, but in no way does the example try to implement any multi-tenant features. When I was trying to think of an example, the first thing that came to mind was a Stack Overflow question where the poster was having trouble with method parameter injection, and the domain of the question was about multi-tenancy. So the example kind of stuck in my head.

The code can be found on GitHub as a single Gist file. I didn’t think it was necessary to create a complete project for this. The class is a JUnit test class using Jersey Test Framework. So just run it like any other JUnit test. There is only one Maven dependency to make it work, which is listed in the comments.

If you look at the file, you will see a lot of things commented out. This is on purpose. What I will do is start with a first example, and as we move along I will have you un-comment things to demonstrate something else.

So let’s get started. We are going to start with a simple Tenant class, which we want to inject into a method parameter.

public static class Tenant {
    public String name;
    public Tenant(String name) { this.name = name; }
}

The first example is a working example. We will inject the Tenant using the @Context annotation, which is known by Jersey. If you look at the first paragraph, this is what I mean by “non-custom” injection. Later we will try to use our own annotation, which is what I consider “custom” injection.

@Path("with-context")
public static class WithContextNoOther {

    @GET
    public String get(@Context Tenant tenant) {
        return tenant.name;
    }
}

To make this work, we will use an HK2 Factory to create the Tenant

public static class TenantFactory implements Factory<Tenant> {

    @Override
    public Tenant provide() { return new Tenant(TENANT_NAME); }

    @Override
    public void dispose(Tenant t) { }
}

Then we need to bind the factory to HK2 in a AbstractBinder, then register the binder with the ResourceConfig

public static class TenantBinder extends AbstractBinder {
    @Override
    protected void configure() {
        bindFactory(TenantFactory.class).to(Tenant.class);
    }
}

@Override
public ResourceConfig configure() {
    return new ResourceConfig()
            .register(new TenantBinder())
            .register(WithContextNoOther.class)
            .register(DebugMapper.class);
}

If you run the test, you will see that it passes.

@Test
public void should_return_tenant_with_Context_injection() {
    Response response = target("with-context").request().get();
    assertEquals(200, response.getStatus());
    assertEquals(TENANT_NAME, response.readEntity(String.class));
}

The injection works fine as expected. Next we will add a another method parameter, which will be the entity body of the request. This is just so we have some context later on.

@Path("with-context-and-entity")
public static class WithContextAndEntity {

    @POST
    public String post(@Context Tenant tenant, String body) {
        return tenant.name + ":" + body;
    }
}

To run the test on this endpoint, you should un-comment the configuration where I register the class

@Override
public ResourceConfig configure() {
    return new ResourceConfig()
            .register(new TenantBinder())
            .register(WithContextNoOther.class)
            .register(WithContextAndEntity.class)
            .register(DebugMapper.class);
}

And un-comment the @Test method.

@Test
public void should_return_tenant_with_Context_injection_and_entity() {
    Response response = target("with-context-and-entity").request()
            .post(Entity.text(MESSAGE_BODY));
    assertEquals(200, response.getStatus());
    assertEquals(NAME_AND_MESSAGE, response.readEntity(String.class));
}

You will see that this also passes. But now we want to inject with a custom annotation, say

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public static @interface TenantParam {}

If you’ve ever used a custom annotation or if you look at the Jersey user guide link I provided above, you will see that in order to use a custom annotation for injection, we need to provide our own InjectionResolver. Here is the implementation we will use for the example

public static class TenantParamResolver implements InjectionResolver<TenantParam> {
    
    @Inject
    @Named(InjectionResolver.SYSTEM_RESOLVER_NAME)
    InjectionResolver<Inject> systemInjectionResolver;

    @Override
    public Object resolve(Injectee injectee, ServiceHandle<?> root) {
        if (Tenant.class == injectee.getRequiredType()) {
            return systemInjectionResolver.resolve(injectee, root);
        }
        return null;
    }

    @Override
    public boolean isConstructorParameterIndicator() { return false; }

    @Override
    public boolean isMethodParameterIndicator() { return false; }   
}

Then we will register the InjectionResolver in our AbstractBinder. Just un-comment the part in the TenantBinder where we register it

public static class TenantBinder extends AbstractBinder {
    @Override
    protected void configure() {
        bindFactory(TenantFactory.class).to(Tenant.class);
        bind(TenantParamResolver.class)
                .to(new TypeLiteral<InjectionResolver<TenantParam>>(){})
                .in(Singleton.class);
    }
}

Here is the resource class/method we will use to test

@Path("with-custom")
public static class WithCustomNoOther {

    @GET
    public String get(@TenantParam Tenant tenant) {
        return tenant.name;
    }
}

And un-comment the registration of the resource class, and also the @Test method for this test

@Override
public ResourceConfig configure() {
    return new ResourceConfig()
            .register(new TenantBinder())
            .register(WithContextNoOther.class)
            .register(WithContextAndEntity.class)
            .register(WithCustomNoOther.class)
            .register(DebugMapper.class);
}

@Test
public void should_return_tenant_with_Custom_injection() {
    Response response = target("with-custom").request().get();
    assertEquals(200, response.getStatus());
    assertEquals(TENANT_NAME, response.readEntity(String.class));
}

When you run the test you will see two things. The first is that the test assertion fails, as it expects a 200 response, but we get a 500. Second, if you look at the log (or console), you will see that we logged a NullPointerException where we tried to call tenant.name in the resource method. This is because the injection failed, and the Tenant never got injected.

Now before we try to fix this, let’s try out something else to see a different result. First comment back out the previous @Test. We don’t care for it right now. Also comment out the registration of the WithCustomNoOther.class. What we will do here is use the WithCustomAndEntity.class. We will not test it though, we will only register it.

@Path("with-custom-and-entity")
public static class WithCustomAndEntity {

    @POST
    public String post(@TenantParam Tenant tenant, String body) {
        return tenant.name + ":" + body;
    }
}

@Override
public ResourceConfig configure() {
    return new ResourceConfig()
            .register(new TenantBinder())
            .register(WithContextNoOther.class)
            .register(WithContextAndEntity.class)
            //.register(WithCustomNoOther.class)
            .register(WithCustomAndEntity.class)
            .register(DebugMapper.class);
}

So at this point, the only thing that should be changed from the previous successful test, is that we just registered the WithCustomAndEntity.class. We should still only have the previous successful @Test methods un-commented.

Now run the test and see what happens….

What the heck! Both tests fail, when previously they passed, and all we did was register a new resource class. Part of the error/exception reads

org.glassfish.jersey.server.model.ModelValidationException: Validation of the application resource model has failed during application initialization

If you remember the previous failing test, hopefully you noticed that this is a completely different exception. The previous exception was a NullPointerException, meaning that the endpoint was actually being hit. This new exception actually caused the server to not even start. You will see that no requests were logged from our LoggingFilter.

So what is this ModelValidationException? Well anytime you create an object-oriented application, you want to carefully model your application domain. This way you can just process the domain objects. With this same concept in mind, Jersey models its application domain, which consists of resources and resource methods, etc. Behind the scene, these concepts are modeled as Resource and ResourceMethod, respectively.

On startup, Jersey validates these model components to make sure that they follow the rules, ensuring there are no unexpected problems at runtime related resource definitions. Part of the validation consists of making sure that all method parameters are injectable. When Jersey sees that something is not injectable, it will raise a flag and throw an exception, making sure we fix the problem.

When scanning the resource methods, Jersey introspects the method parameters looking to make sure that each parameter has a ValueFactoryProvider that can handle the injection. This is what the documentation fails to mention. The InjectionResolver is enough to handle field and constructor injection, but not for method parameter injection. The reason it works for @Context is that there is a ValueFactoryProvider that handle the @Context annotated parameters.

The reason we didn’t get this exception on the first fail to

@GET
public String get(@TenantParam Tenant tenant) {
    return tenant.name;
}

is that we are allowed to have one method parameter as the entity body parameter. I’m sure you’ve noticed in your experience with Jersey, that when you want a method parameter to be the body, say a JSON-parsed-to-POJO body, you don’t use an annotation (unless its for form or multipart). This is allowed for one method parameter. A request should only have one entity body, therefore only one entity parameter is allowed. There is even a EntityParamValueFactoryProvider to handle this one entity parameter. The reason we get the exception with

@POST
public String post(@TenantParam Tenant tenant, String body) {
    return tenant.name + ":" + body;
}

is that the @TenantParam is not recognized by the validator. So it thinks there may be two entity body parameters. It validates the Tenant just fine, but then it gets to the second parameter, which is also assumed to be and entity. So the exception points to the String parameter, and not the Tenant parameter.

No injection source found for a parameter of type public java.lang.String

So with all that being said, the fix here is to provide a ValueFactoryProvider. The main method is the Factory<?> getValueFactory(Parameter) method, which returns a Factory. In the method, we should check the Parameter argument to see if we can handle it. If not we just return null. What happens on startup is that all the ValueFactoryProviders registered are traversed while trying to validate each parameter. If none of the providers return a Factory for the parameter, then a validation error is thrown. Since the EntityParamValueFactoryProvider can only handle one parameter for each resource method, the first method parameter get the provider, and the second doesn’t, and the traversal returns null.

Here is the example ValueFactoryProvider we will use.

public static class TenantParamValueProvider implements ValueFactoryProvider {

    @Override
    public Factory<?> getValueFactory(Parameter parameter) {
        if (parameter.getRawType() == Tenant.class
                && parameter.isAnnotationPresent(TenantParam.class)) {
            return new TenantFactory();
        }
        return null;
    }

    @Override
    public ValueFactoryProvider.PriorityType getPriority() {
        return Priority.NORMAL;
    }
}

Here’s we just check that the parameter is of type Tenant and that it is annotated with @TenantParam. Any other parameter qualifications, we cannot handle and just return null. Now just un-comment the registration of this provider in the TenantBinder

public static class TenantBinder extends AbstractBinder {
    @Override
    protected void configure() {
        bindFactory(TenantFactory.class).to(Tenant.class);
        bind(TenantParamResolver.class)
                .to(new TypeLiteral<InjectionResolver<TenantParam>>(){})
                .in(Singleton.class);
        bind(TenantParamValueProvider.class)
                .to(ValueFactoryProvider.class)
                .in(Singleton.class);
    }
}

Make sure all the resource classes are registered

@Override
public ResourceConfig configure() {
    return new ResourceConfig()
            .register(new TenantBinder())
            .register(WithContextNoOther.class)
            .register(WithContextAndEntity.class)
            .register(WithCustomNoOther.class)
            .register(WithCustomAndEntity.class)
            .register(DebugMapper.class);
}

And un-comment all the @Test methods. There should be four in total. Then run the test… and Woo Hoo!. We passed.

If you look at the bottom of the test class, you will see a TenantParamValueFactoryProvider. This is a model I use for many of the param providers I create. I closely models how Jersey creates them. You can look in this package for some of the providers that handle such parameters like @PathParam and @QueryParam.

In this implementation you will notice that the TenantFactory, instead of implementing Factory, it extends AbstractContainerRequestValueFactory. This is a convenience class that gives us access the ContainerRequest, which is the context of the request. You can get a lot of information from it. Also instead of directly implementing InjectionResolver, we extend ParamInjectionResolver. This is also a convenience class that needs to get passed an instance of AbstractValueFactoryProvider (which is actually a ValueFactoryProvider).

To see this version work, you can un-comment the registration of its Binder and comment the registration of the TenantBinder

@Override
public ResourceConfig configure() {
    return new ResourceConfig()
            //.register(new TenantBinder())
            .register(new TenantParamValueFactoryProvider.Binder())
            .register(WithContextNoOther.class)
            .register(WithContextAndEntity.class)
            .register(WithCustomNoOther.class)
            .register(WithCustomAndEntity.class)
            .register(DebugMapper.class);
}

And that’s it. Hope you guys found this article informative.

Creating Reusable Jersey Extensions (Features)

Fri, 23 Oct 2015 00:00:00 -0700

When developing in Jersey, you may find yourself reusing some components for different projects, or you would like to share your components with the world to use. In either case, it is likely the components will need to be configured to suit the user’s needs. In this article I will show a pattern of how to create these reusable components and to package them up into easily usable and configurable features.

The pattern I will be describing is the pattern used by most of the features in Jersey. For example, you might find yourself doing this

register(SomeFeature.class);
property(SomeFeature.SOME_PROPERTY, false);
property(SomeFeature.ANOTHER_PROPERTY, true);

Here we are registering the SomeFeature and setting configuration properties on that feature. This is the usability pattern we will follow in the example I describe in this article.

The example we will use is an API key feature that allows clients to obtain a API key to use your APIs. Do note that the implementation should probably not be used in the real world. I put more thought into creating the framework components and making them fit, than into any security good practices.

So these are the requirements we will try to meet.

When a client tries to access an endpoint, if a API key header is not set with a valid key, the client will get sent an Unauthorized response.
The client can obtain a key from an endpoint created by the feature.

For the first of the bullet points we will use a ContainerRequestFilter. For the second point, we will create an endpoint class just like any other resource class you create in Jersey.

Configurables

The user should be able to configure how the key is generated.
The user should be to configure their own data access.
The user should be able to configure the API key endpoint URI.
The user should be able to configure the header name the key should come in.
The user should be able to add test data to a default (in-memory) data store.

All the code examples can be found in the GitHub project. The code discussed here will be from the jersey-extension-framework child project, and the client of the feature project can be found in the jersey-extension-client child project

The first component we will introduce is the ClientStore.

public interface ClientStore {
    void saveClient(ClientDetails clientDetails);
    ClientDetails getClientById(String clientId);
    ClientDetails getClientByApiKey(String apiKey);
}

These methods will allow the feature to lookup clients from the data store, and to save clients. There is a default implementation (DefaulClientStore) provided that will just save to a ConcurrentHashMap. The user of the feature can use this default just to test, but will want to provide their own implementation that will actual store the data to a persistent store.

The ClientDetails is a simple domain model that has three properties.

public class ClientDetails {
    private String clientId;
    private String clientPassHash;
    private String apiKey;
    // getters and setters
}

The next component is the ApiKeyFilter, which is a ContainerRequestFilter. This will filter out the requests to check for API keys

final class ApiKeyFilter implements ContainerRequestFilter {
    
    private final String authEndpoint;
    private final String apiKeyHeader;
    
    @Inject
    private ClientStore clientStore;
    
    public ApiKeyFilter(String authEndpoint, String apiKeyHeader) {
        this.authEndpoint = authEndpoint;
        this.apiKeyHeader = apiKeyHeader;
    }

    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {
        String requestUri = requestContext.getUriInfo().getRequestUri().toString();
        if (requestUri.endsWith(authEndpoint)) {
            return;
        }
        
        String keyValue = requestContext.getHeaderString(apiKeyHeader);
        if (keyValue == null) {
            throw new WebApplicationException(Response.Status.UNAUTHORIZED);
        }
        
        ClientDetails client = clientStore.getClientByApiKey(keyValue);
        if (client == null) {
            throw new WebApplicationException(Response.Status.UNAUTHORIZED);
        }
    }
}

As stated earlier, the API key endpoint is configurable, and so it the API key header. So we provide those in a dependencies through the constructor. In th filter method we check three things

If the request is to the API key endpoint, we let it through.
If the API key is missing, the client will get an Unauthorized response.
If the client can’t be found through the API key, they will also get an Unauthorized response.

The next component we will create the ApiKeyEndpoint. This is the endpoint requested to get a key.

@Path(ApiKeyFeature.DEFAULT_URI)
@Produces(MediaType.APPLICATION_JSON)
public class ApiKeyEndpoint {
    
    @Inject
    private KeyGenerator keyGenerator;
    
    @Inject
    private ClientStore clientStore;

    private Response getApiKey(ClientPostInfo clientInfo) {
        ClientDetails client = clientStore.getClientById(clientInfo.clientId);
        if (client == null) {
            throw new WebApplicationException(Response.Status.UNAUTHORIZED);
        }
        String hash = noOpHash(clientInfo.clientPass);
        if (!client.getClientPassHash().equals(hash)) {
            throw new WebApplicationException(Response.Status.UNAUTHORIZED);
        }
        String apiKey = keyGenerator.generateKey(client.getClientId());
        client.setApiKey(apiKey);
        clientStore.saveClient(client);
        return Response.ok(new ApiKey(apiKey)).build();
    }
}

I took out some code for brevity, but you can find the complete code in the project. The main functionality of the endpoint is enclosed in the getApiKey method. There are actually two resource methods, one to handle application/json POST data, and one to handle application/x-www-form-urlencoded POST data. They both make the same call to the getApiKey method, so I just left them out.

In the getApiKey method we look up the ClientDetails from the ClientStore. If the client is not in the store, they get an Unauthorized response. In this example we will assume the client it put into the store in some out of band way, so the feature will be so concerned with being able to add clients to the store.

If the client is found, then they will be issued an API key, in JSON form. For example

{"apiKey" : " dj8e2-d2idj-wed32-32jdw"}

The other thing to note about this class is the KeyGenerator. This is another interface the user can implements and configure.

public interface KeyGenerator {
    String generateKey(String clientId);
}

There is a default one (UUIDKeyGenerator) that does nothing more than return a random UUID.

These are all the main components involved in the actual functionality of the feature. I tried to keep it sweet and simple. To use the feature the user should be able to do the following

property(ApiKeyFeature.API_KEY_HEADER, "X-API-TOKEN");
property(ApiKeyFeature.API_KEY_URI, "apikey");
property(ApiKeyFeature.CLIENT_STORE_CLASS, JpaClientStore.class);
property(ApiKeyFeature.KEY_GEN_CLASS, SomeKeyGenerator.class);

register(ApiKeyFeature.class);

In this example the user is opting to change the default properties by supplying their own. Hopefully you can figure the use of the first two. The latter two are the two components implemented by the user, and provided to the feature, which overrides the default components. Then the user registers the ApiKeyFeature which we will described shortly. The thing to note is that we will have defaults for all these properties.

Also if the user wanted to test out the feature just using the DefaultClientStore, then they would not have to configure the ApiKeyFeature.CLIENT_STORE_CLASS property. Instead they should use ApiKeyFeature.INIT_CLIENT_DATA to supply a List<ClientDetails> as the property value. This will be the initial data to put into the store.

Now here is where the main configuration component comes in, the ApiKeyFeature. It is a lot of code to put into on code block, so I will go through it piece by piece. So to follow along, you should open up the file.

The first to check out are the couple of helper methods at the bottom of the class.

public static <T> T getValue(Map<String, ?> properties, String key, Class<T> type) {
    return PropertiesHelper.getValue(properties, key, type, null);
}

public static <T> T getValue(Map<String, ?> properties, String key, T defaultValue) {
    return PropertiesHelper.getValue(properties, key, defaultValue, null);
}

I just copied these from a different feature in the Jersey project. They just help in obtaining property values from the property map. For example at the beginning of the configure method, you will see

@Override
public boolean configure(FeatureContext context) {
    Map<String, Object> properties = context.getConfiguration().getProperties();

    final String apiKeyHeader = getValue(properties, API_KEY_HEADER, DEFAULT_KEY_HEADER);
    
    final String apiKeyPath = getValue(properties, API_KEY_URI, DEFAULT_URI);

    context.register(new ApiKeyFilter(apiKeyPath, apiKeyHeader));
    ...
}

When a user set a property in the ResourceConfig by calling property(prop, value);, The property gets set the Configuration properties, that we obtains from the FeatureContext. Then we look then up with our helper methods, supplying default values. So if the API_KEY_HEADER is not set, then use the DEFAULT_KEY_HEADER. Same goes for the API_KEY_URI. After we obtain these two properties, then we can construct the ApiKeyFilter, and then register the filter with the application.

Next we are going to programmatically create the ApiKeyEnpoint resource. This is required because the URI is configurable. When the user provides a different URI from the default, we need to reconstruct the resource model. To do this we will use a combination of a Resource.Builder and a ModelProcess. Details about using these components is outside the scope of this article. To get more information on programmatically creating resources, I suggest you check out Programmatic API for Building Resources

final Resource apiKeyResource
           = Resource.builder(ApiKeyEndpoint.class).path(apiKeyPath).build();
context.register(new ApiKeyModelProcessor(apiKeyResource));
[...]
private static class ApiKeyModelProcessor implements ModelProcessor {

    private final Resource apiKeyResource;

    public ApiKeyModelProcessor(Resource apiKeyResource) {
        this.apiKeyResource = apiKeyResource;
    }

    @Override
    public ResourceModel processResourceModel(ResourceModel resourceModel,
            Configuration config) {
        ResourceModel.Builder builder
                = new ResourceModel.Builder(resourceModel.getResources(), false);
        builder.addResource(apiKeyResource);
        return builder.build();
    }
}

The last part of the Feature configuration is to handle the KeyGenerator and the ClientStore.

Class<? extends KeyGenerator> generatorCls = getValue(properties, KEY_GEN_CLASS, Class.class);
generatorCls = generatorCls == null ? UUIDKeyGenerator.class : generatorCls;

Class<? extends ClientStore> clientStoreCls = getValue(properties, CLIENT_STORE_CLASS, Class.class);
// Using DefaultClientStore. 
if (clientStoreCls == null) {
    DefaultClientStore defaultClientStore = new DefaultClientStore();
    List<ClientDetails> db = getValue(properties, INIT_CLIENT_DATA, List.class);
    if (db == null) {
        throw new RuntimeException("Either set ClientStore or init List");
    }
    for (ClientDetails c : db) {
        defaultClientStore.saveClient(c);
    }
    context.register(new ApiKeyBinder(defaultClientStore, generatorCls));
} else {
    context.register(new ApiKeyBinder(clientStoreCls, generatorCls));
}

The first couple of lines set the KeyGenerator class. If the property is not set, getValue will return null. In that case we use the default UUIDKeyGenerator.

For the ClientStore it will be a bit different. If the user doesn’t set their own ClientStore implementation, then they can set the List<ClientDetails> to initialize the DefaultClientStore with come data. In which case we will use an instance of the DefaultDataStore instead of the class. This is necessary to initialize the data.

Once we have the KeyGenerator class and the ClientStore class or DefaultClientStore instance, we will register then with an AbstractBinder, which is used by Jersey’s dependency injection framework HK2 to register the services. These services are injected into both the ApiKeyFilter and the ApiKeyEndpoint. To learn more about HK2 and using it with Jersey, see Custom Injection and Lifecycle Management

And that’s it for the feature. You can see the test cases in the project. There are two sets of tests. Both of which extend from BaseApiKeyFeatureTest. One of the test sets use all defaults, while the other uses all configured properties.

You can also see the jersey-extension-client project to see a real client of the feature in action. It implements the ClientStore using JPA. Instructions to run the client project are its README.

Hope you enjoyed this article and hope you start building and sharing your new features!

Why and How to Use Spring With Jersey?

Mon, 19 Oct 2015 00:00:00 -0700

I’ve seen a few question on Stack Overflow where people are confused about the difference between Jersey and Spring MVC, and I thought it would be a good opportunity to try and demystify some of the confusion. In this article I will first go through some analysis on why we should (or shouldn’t) mix the two frameworks, then I will get into some example implementation.

WHY?

So why use Spring with Jersey? First notice the careful naming of the title. It’s not “Using Jersey with Spring”. That title would imply a Spring application integrating Jersey, while the current title implies integrating Spring into a Jersey application. It’s a subtle difference as far as the title is concerned, but a difference that should be acknowledged for this discussion. An article on “integrating Jersey into Spring” might be more aimed at Spring users that would like to learn Jersey, and may give some tutorial on beginning Jersey stuff. This article is not that. This article assumes you know Jersey, and are thinking about integrating Spring into your Jersey application.

Now to answer the question of “why integrate?”, it helps to look at an application architecture from the three-tier view. Anyone who’s had any experience creating an enterprise web application should be familiar with this architecture. It is basically modeled as shown below

In a web application, the Presentation Layer would normally consist of the view/controller layer in an MVC framework. The Business Layer would consist of the business services and the Persistence Layer would consist of the repositories (or DAOs) that interact with the Database. No layer can interact with the above layer, and each layer only interacts with the layer below it. In code form, it might translate to something like

public class Controller {
    private CusotomerService customerService;
}

public class CustomerService {
    private CustomerRepositoty customerRepository;

    public Customer findCustomer(long id) {
          return customerRepository.findById(id);
      }
}

public class CustomerRepository {
    private EntityManager em;

    public Customer findById(long id) {
        return em.find(Customer.class, id):
    }
}

The Controller is part of the presentation layer, the CustomerService is in the business layer, and the CustomerRepository is in the persistence layer. As you can see, the constraints I described above are maintained in this example. The presentation layer only interacts with the business layer, the business layer only interacts with the persistence layer, and the persistence layer only interacts with the database.

In this example, the business layer and persistence layer may seem redundant, but in a real application, the service layer also handles the business logic of the domain, not just a simple “find data”, but also “do manipulate data”. The persistence layer should only be concerned with database interactions, and not with any business logic.

So back to the topic at hand. In a REST application, there is no presentation layer. But does that mean that this architecture doesn’t apply to REST applications? Absolutely not. We should still adhere to this separation of concerns in REST applications. It is just good design.

So with that being said, we can say that instead of a presentation layer, the presentation layer is replaced with a “REST interface layer” or “REST layer”. AFAIK there is no such term widely used, it’s just something I made up for the sake of this discussion.

With Spring, its REST layer is implemented in its MVC framework. The MVC framework is widely know for its MVC capabilities with the use of controllers. But with a little tweaking of the controllers and the annotations used, the controllers can easily become a REST controller, where instead of return models and views, you are return RESTful representation objects.

So Spring already comes with REST support. What my time on Stack Overflow has shown me, is that there is not a lot of enthusiasm from established Spring users to learn and/or switch over to using Jersey as the REST layer, even though you can use Spring components (business, persistence) with a Jersey application. And it makes sense. Why learn a different framework, when the one I am using and am comfortable with using, works just fine? So that is part of the reasoning behind why I specifically made this article about integrating Spring with Jersey and not the other way around.

Really there is no difference in implementation. Integrating Spring with Jersey and integrating Jersey with Spring mean the same thing as far as code is concerned. I am pretty much just giving an analysis to answer the question (which I’ve seen a few times on Stack Overflow), “As a Spring user, why should I learn Jersey?” Answer - If you don’t want to… Don’t. If you’re comfortable with implementing REST controllers with Spring, then more power to you. Stick with what you know. The only answer I could give that makes any sense to “why” is “it doesn’t hurt to learn new things.”

So now let’s try and answer the question “Why integrate Spring into Jersey?”. The core features of Spring are Dependency Injection and AOP. But Jersey already has a Dependency Injection framework in HK2. And HK2 has support for AOP. So the core of Spring wouldn’t be the reason we would want to integrate. But then we get to the persistence layer. Spring has great persistence support. For example with Spring Data, we get free support for common CRUD operations, without having to implements a single method. For example all we need is this

public interface CustomerRepository implements JpaRepository<Customer, Long> {}

Notice that it’s just an interface. We don’t need to create a concrete class. That’s it, and we get nearly 20 free methods that handle normal CRUD operations. Here are some to name a few

List<Customer> findAll()
Customer findOne(Long id)
Customer save(Customer c)
void delete(Customer c)

And there are more. You can view all of the in the javadocs. Let’s say we want to find Customers by firstName. All we do is declare a method in the interface

public interface CustomerRepository implements JpaRepository<Customer, Long> {
    List<Customer> findByFirstName(String firstName);
}

Spring Data uses a domain specific language that parses the method signature. As long as we follow the rules, there are unlimited possibilities with the method signatures. And we never have to implement anything. Spring data handles all of it under the hood.

Also we get transaction support in a declarative way. If you were to try an implement your own DAO layer in Jersey, you might find alot of this all over the place

public Customer save(Customer c) {
    entityManager.getTransaction().begin();
    entityManager.perist(c);
    entityManager.getTransaction().commit();
    return c;
}

We are explicitly handling the transaction ourselves, where with Spring transaction support, we can just declare our service method as @Transactional

public class CustomerService {
    public CustomerRepository customerRepository;

    @Transactional
    public Customer save(Customer c) {
        return customerRepository.save(c);
    }
}

Spring will transparently handle the transactions in an AOP way.

The example above is for JPA (hence JpaRepository), but Spring data has a wide range of other types databases other than relational ones. For instance MongoDB, or Neo4j. Spring Data offer similar repository support. To learn more about the different Spring Data project, you should check out the reference guides in the Spring Reference Documentations.

Going through the previous link, you will see that Spring has a rich ecosystem. In a Jersey project, we could bind our service layer to Spring, and from there all those services have access to a wide range of other Spring projects.

So I hope that gives you an idea of why you should consider integrating. If not for the ecosystem, I’d say it’s a good argument that simply taking into account the persistence support, that is a good enough reason to consider integrating.

Implementation

So let’s get into some implementation. You can find the complete project as Github.

What you will need to make the most of this guide are:

cURL - A command line tool that I use as a REST client. You may use a different client, but any other tools usages will be outside the scope of this article.
Maven - To build and run the app with the jetty-maven-plugin

You can clone the project

git clone https://github.com/psamsotha/jersey-spring-example.git

Or download it from

https://github.com/psamsotha/jersey-spring-example

What I will cover will be as follows

Dependencies
Basic Configuration
Component Implementation
Running and Testing with cURL

Maven Dependencies

So we are creating a new Maven web project. The following dependencies are ones we going to use. Note that there are exclusions in the jersey-spring3 dependency. We want to replace the Spring 3 dependencies with Spring 4, and also exclude some conflicting bean validation transitive dependencies. The exclusion are not shown in the following list. Please the pom in the Github project

<dependencies>
    <dependency>
        <groupId>org.glassfish.jersey.containers</groupId>
        <artifactId>jersey-container-servlet</artifactId>
        <version>${jersey.version}</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jersey.media</groupId>
        <artifactId>jersey-media-json-jackson</artifactId>
        <version>${jersey.version}</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jersey.ext</groupId>
        <artifactId>jersey-spring3</artifactId>
        <version>${jersey.version}</version>
        <exclusions>
          ...
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.springframework.data</groupId>
        <artifactId>spring-data-jpa</artifactId>
        <version>1.9.0.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.hibernate</groupId>
        <artifactId>hibernate-entitymanager</artifactId>
        <version>5.0.1.Final</version>
    </dependency>
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <version>1.4.182</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-web</artifactId>
        <version>4.1.7.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

jersey-spring3 is the dependency that has the Spring integration components. One thing to note about the jersey-spring3 dependency is that as of this writing, jersey-spring4 is in the master branch of the Jersey project. So it appears that in the next release Spring 4 will be supported, so we won’t need to use jersey-spring3 with exclusions (unless of course the Spring 4 version is older than the one we want to use). The jersey-media-json-jackson is for JSON/POJO support.

For Spring Data JPA, we added the spring-data-jpa dependency. This will pull in a bunch of other Spring 4.1.7.RELEASE jars. Then we have hibernate-entitymanager, which will be our JPA implementation. h2 will be out in-memory database we will use for testing.

Basic Configuration

Here we will cover both Jersey and Spring. The way we will implement this application is web.xml-less. For Jersey, this will be made possible with the jersey-container-servlet dependency. Note that for this to work, the application must be run an Servlet 3.x container. For example Tomcat 7, will work, but Tomcat 6 will not work as it is a Servlet 2.5 container. We will simply be running with the Jetty Maven plugin, which will be a Servlet 3.1 container.

The following is all that we need for Jersey configuration (see the actual project for import statements)

@ApplicationPath("/api")
public class AppConfig extends ResourceConfig {
    
    public AppConfig() {
        packages("com.underdog.jersey.spring.example.resource");
          register(RequestContextFilter.class);
          property(ServerProperties.RESPONSE_SET_STATUS_OVER_SEND_ERROR, true);
    }
}

The @ApplicationPath annotation works similar to the <servlet-mapping> in a web.xml. The /api value will the root path of our application. The packages method tells Jersey to scan the com.underdog.jersey.spring.example.resource package for our resources (classes annotated with @Path). The RequestContextFilter is provide a bridge between Jersey and the Spring request attributes. The property we set is so that instead of the server sending a server error page on error statuses, it just sends the status code.

For the Spring configuration, we have two different components. The first is the Spring application configuration. For this app this will mostly consist of persistence configuration. (Again see project for import statements)

@Configuration
@EnableTransactionManagement
@ComponentScan("com.underdog.jersey.spring.example.service")
@EnableJpaRepositories("com.underdog.jersey.spring.example.repository")
public class SpringConfig {

    @Bean
    public DataSource dataSource() {
        return new EmbeddedDatabaseBuilder()
                .setType(EmbeddedDatabaseType.H2)
                .addScript("classpath:schema.sql")
                .addScript("classpath:data.sql")
                .build();
    }

    @Bean
    public JpaTransactionManager transactionManager(EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }

    @Bean
    public JpaVendorAdapter jpaVendorAdapter() {
        HibernateJpaVendorAdapter jpaVendorAdapter = new HibernateJpaVendorAdapter();
        jpaVendorAdapter.setDatabase(Database.H2);
        jpaVendorAdapter.setShowSql(true);
        jpaVendorAdapter.setGenerateDdl(false);
        return jpaVendorAdapter;
    }

    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
        LocalContainerEntityManagerFactoryBean lemfb 
                = new LocalContainerEntityManagerFactoryBean();
        lemfb.setDataSource(dataSource());
        lemfb.setJpaVendorAdapter(jpaVendorAdapter());
        lemfb.setPackagesToScan("com.underdog.jersey.spring.example.domain");
        return lemfb;
    }
}

The @EnableTransactionManagement is so that we can use annotation driven transaction management, meaning we can just add @Transactional onto our service classes/methods.

The @Component scan tells Spring to scan the declared package for our Spring service components.

The @EnableJpaRepositories tell Spring to scan the declared package for Spring repository extension, i.e. our CustomerRepository.

All the @Bean implementations are the basic beans that need to be configured to bootstrap JPA persistence support. In order of declaration, we have configured the in-memory database, the transaction manager, the JPA implementation (Hibernate) and the EntityManagerFactory for JPA. One thing to note about the in-memory database configuration is that we are using a couple sql scripts to create the table and insert the initial data. You can look in the src/main/resources for those files.

The next Spring configuration component we will use is a WebApplicationInitializer to bootstrap the Spring components in a xml-less way. The odd looking init-param ("contextConfigLocation", "noop") is needed to avoid this bug. To get some explanation about how the WebApplicationInitializer works, you can see this Stack Overflow question.

@Order(1)
public class SpringInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext sc) throws ServletException {
        sc.setInitParameter("contextConfigLocation", "noop");
        
        AnnotationConfigWebApplicationContext context
                = new AnnotationConfigWebApplicationContext();
        context.register(SpringConfig.class);
        sc.addListener(new ContextLoaderListener(context));
          sc.addListener(new RequestContextListener());
    } 
}

The important thing to note about this components is the @Order(1). We want to make sure this initializer occurs before Jersey tries to create the app context. If we fail to do this, Jersey will look for a applicationContext.xml Spring configuration file. When it doesn’t find it we will get a FileNotFoundException. Since we don’t want to use xml configuration, we need to include the initializer.

Component Implementation

The JPA entity we will use a simple Customer class with an id, firstName, and lastName

@Entity
public class Customer {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private long id;
    private String firstName;
    private String lastName;
    // Getters and Setters
}

Then we have our Spring Data JPA repository.

public interface CustomerRepository extends JpaRepository<Customer, Long> {
    List<Customer> findByFirstNameAndLastName(String firstName, String lastName);
}

As discussed earlier, this is nothing more than an interface. We never have to implement this, but with this we get a bunch of free implementations. The only extra method we added, is one to search for Customer by their first and last name. This method name follows the Spring Data DSL for method naming convention. We return a List<Customer> instead of just a single Customer, as it is possible for more than one customer to have the same name.

In the next component, the service layer component, you can actually see the usage of the repository’s “free” methods. I will not show all the method, just for brevity, but you can see the project code for the entire implementation.

@Service
@Transactional
public class CustomerServiceImpl implements CustomerService {
    
    @Autowired
    private CustomerRepository customerRepository;

    @Override
    public List<Customer> findAll() {
        return customerRepository.findAll();
    }

    @Override
    public Customer findOne(Long id) {
        return customerRepository.findOne(id);
    }

    @Override
    public Customer save(Customer customer) {
        return customerRepository.save(customer);
    }

    @Override
    public List<Customer> findByFirstAndLastName(String fname, String lname) {
        return customerRepository.findByFirstNameAndLastName(fname, lname);
    } 
}

As you can see the only method we added to the interface was the findByFirstNameAndLastName, which we use here in the service class, but also we make use of the free repository methods in out other service methods.

The last application component is the Jersey resource class. I will only show a couple methods. You can find the rest in the project source code.

@Path("customers")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class CustomerResource {
    
    @Autowired
    private CustomerService customerService;
    
    @GET
    public Response getAllCustomers(@QueryParam("firstName") String firstName,
                                    @QueryParam("lastName") String lastName) {
        
        List<Customer> customers;
        if (firstName != null && lastName != null) {
            customers = customerService.findByFirstAndLastName(firstName, lastName);
        } else {
            customers = customerService.findAll();
        }
        return Response.ok(new GenericEntity<List<Customer>>(customers){}).build();
    }
    
    @POST
    public Response createCustomer(Customer customer, @Context UriInfo uriInfo) {
        customer = customerService.save(customer);
        long id = customer.getId();
        
        URI createdUri = uriInfo.getAbsolutePathBuilder().path(Long.toString(id)).build();
        return Response.created(createdUri).build();
    }
}

We inject the CustomerService into our resource class with the @Autowired annotation. The interesting thing about the getAllCustomers endpoint is that we include an optional search by first name and last name. If these filter parameters are included, we will call the custom repository’s method. If these parameters are missing, we just return all the customers.

In the other resource method, we implement a POST to create a customer resource. When customer is created, it gets an id. From that id, we create the new resource URI, and pass it to the created method, which will send a 201 Created status along with a Location header with the new resource URI.

Running and Testing with cURL

In testing our application will will use cURL. For a real application, you will probably also want to include automated JUnit tests, but I consider myself to be a pretty thorough tester, so for me to implement the JUnit tests in this example application would pretty much double the work. And this article is not really about testing. In future articles I may cover testing with Jersey.

What we will do is the following

Make a GET to get all the customers
Make a GET to get customers by first and last name
Create a customer through a POST
Make a GET request for the customer we previously created
Make a PUT request to update a customer
And finally delete a customer.

First thing you will want to do is start the server. cd to the project root, and use the jetty-maven-plugin to start the server.

cd jersey-spring-example
mvn jetty:run

1. Get all Customers

C:\>curl -i http://localhost:8080/api/customers
HTTP/1.1 200 OK
Date: Tue, 20 Oct 2015 03:45:15 GMT
Content-Type: application/json
Content-Length: 251

[
  {"id":1,"firstName":"Michael","lastName":"Jordan"},
  {"id":2,"firstName":"Kobe","lastName":"Bryant"},
  {"id":3,"firstName":"Lebron","lastName":"James"},
  {"id":4,"firstName":"Stephan","lastName":"Curry"},
  {"id":5,"firstName":"Carmelo","lastName":"Anthony"}
]

In our data.sql file you can see that we inserted five customers. So hitting to root /customers resource, we get back all five.

2. Get Customers by First and Last Name

C:\>curl -i "http://localhost:8080/api/customers?firstName=Michael&lastName=Jordan"
HTTP/1.1 200 OK
Date: Tue, 20 Oct 2015 03:47:49 GMT
Content-Type: application/json
Content-Length: 52

[
  {"id":1,"firstName":"Michael","lastName":"Jordan"}
]

As noted earlier, there may be more than one customer that has the same first name and last name. That’s why we return a List. You can see that instead of a single JSON object, we get a JSON array, even though it is only one customer.

3. Create a Customer

C:\>curl -i -X POST -H "Content-Type:application/json" 
         -d "{\"firstName\":\"Charles\", \"lastName\": \"Barkley\"}"
         http://localhost:8080/api/customers
HTTP/1.1 201 Created
Date: Tue, 20 Oct 2015 03:53:47 GMT
Location: http://localhost:8080/api/customers/6
Content-Length: 0

A couple things to note. I am on Windows, so escaping the double quotes is necessary. On Unix machines, you should be able to use single quotes, so you don’t have to escape the double quotes. For example '{"firstName":"Charles"}'

Next you can see that instead of return the any data, a Location header is returned. That is the URI for the newly created Charles Barley customer resource.

4. Get Customer by Id

In the previous step, we created a new customer, and got back a newly created URI, we can now access this URI.

C:\>curl -i http://localhost:8080/api/customers/6
HTTP/1.1 200 OK
Date: Tue, 20 Oct 2015 03:57:57 GMT
Content-Type: application/json
Content-Length: 51

{"id":6,"firstName":"Charles","lastName":"Barkley"}

If you look at the data.sql you will see that I inserted the initial data with ids 1, 2, 3, 4, 5. Since the ids are auto incremented, Charles is created with the new db id of 6. So just like you can access Charles with the /5 path, you can access the others with their appropriate ids in the URI.

5. Update a Customer

C:\>curl -i -X PUT -H "Content-Type:application/json" 
         -d "{\"firstName\":\"Michael\", \"lastName\": \"Jackson\"}"
         http://localhost:8080/api/customers/1
HTTP/1.1 204 No Content
Date: Tue, 20 Oct 2015 04:04:53 GMT

C:\>curl -i http://localhost:8080/api/customers/1
HTTP/1.1 200 OK
Date: Tue, 20 Oct 2015 04:05:02 GMT
Content-Type: application/json
Content-Length: 51

{"id":1,"firstName":"Michael","lastName":"Jackson"}

Here we are making two separate requests. The first to update the customer at the URI /1. Then we GET the same resource to see that it has been updated.

6. Delete a Customer

C:\>curl -i -X DELETE http://localhost:8080/api/customers/1
HTTP/1.1 200 OK
Date: Tue, 20 Oct 2015 04:10:45 GMT
Content-Length: 0

C:\>curl -i http://localhost:8080/api/customers/1
HTTP/1.1 404 Not Found
Date: Tue, 20 Oct 2015 04:10:56 GMT
Content-Length: 0

Here we made two separate requests. One to delete the customer, and the next try and GET it. We will see in the second request, that the resource is no longer available, so we get a 404.

And that wraps up this article. I hope you all found it informative.

Paul Samsotha Blog

Absolute Paths with Angular and Webpack

tsconfig.json

webpack.config.js

Resources

Jersey Pagination With Spring Data JPA

Note

Using Effects in an Angular 2 NgRx Application

Before Login

After Login

Angular 2 Testing with Karma and SystemJS

Table of Contents

Getting Started with Karma

Jasmine Introduction

Setting up Karma and Running Jasmine Tests

Karma Dependencies

Karma Configuration

Test Results

Getting Started with SystemJS

Intro to Modules

SystemJS Quickstart

Importing Modules

Testing with SystemJS

karma-test-shim.js

Adding Angular

Application Setup

Testing Setup

Summary

Working with Jersey Configuration Properties

Table of Contents

Native Capabilities

Custom Injection of Properties

jersey-properties Module

Request Scoped Injection into a Singleton with Jersey

Bonus (Warning!)

Dynamic Proxies and Dependency Injection

Table of Contents:

Proxy Pattern

Dynamic Proxies

Dynamic Proxy and Custom Injection Example

Summary

Custom Method Parameter Injection with Jersey

Creating Reusable Jersey Extensions (Features)

Why and How to Use Spring With Jersey?

Table of Contents:

WHY?

Implementation

Maven Dependencies

Basic Configuration

Component Implementation

Running and Testing with cURL