In order to get started, we need to use some library that provides convenient JSON Web Token operations. In this example we will use JJWT:

<dependency>  
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt</artifactId>
        <version>${jjwt.version}</version>
</dependency>  

Configuring Spring Security

Next, we will configure Spring security to allow access to a login method at /api/login and restrict access to all webservice functions with the pattern /api/secure/**:

<!-- API Security -->  
<http pattern="/api/login" security="none"/>

<http pattern="/api/secure/**" entry-point-ref="jwtAuthenticationEntryPoint" create-session="stateless">  
    <csrf disabled="true"/>
    <custom-filter before="FORM_LOGIN_FILTER" ref="jwtAuthenticationTokenFilter"/>
</http>

<beans:bean id="jwtAuthenticationSuccessHandler" class="com.lukaspradel.jwt.security.JwtAuthenticationSuccessHandler" />

<beans:bean id="jwtAuthenticationTokenFilter" class="com.lukaspradel.jwt.security.JwtAuthenticationTokenFilter">  
    <beans:property name="authenticationManager" ref="jwtAuthMgr" />
    <beans:property name="authenticationSuccessHandler" ref="jwtAuthenticationSuccessHandler" />
</beans:bean>

<authentication-manager id="jwtAuthMgr">  
    <authentication-provider ref="jwtAuthenticationProvider" />
</authentication-manager>  

The related classes look like this:

@Component
public class JwtAuthenticationEntryPoint implements AuthenticationEntryPoint,  
        Serializable {

    private static final long serialVersionUID = 3798723588865329956L;

    @Override
    public void commence(HttpServletRequest request,
            HttpServletResponse response, AuthenticationException authException)
            throws IOException {
        // This is invoked when user tries to access a secured REST resource
        // without supplying any credentials
        // We should just send a 401 Unauthorized response because there is no
        // 'login page' to redirect to
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized");
    }
}

public class JwtAuthenticationSuccessHandler implements  
        AuthenticationSuccessHandler {
    @Override
    public void onAuthenticationSuccess(HttpServletRequest request,
            HttpServletResponse response, Authentication authentication) {
        // Don't do anything specific here
    }

}

public class JwtAuthenticationTokenFilter extends  
        AbstractAuthenticationProcessingFilter {

    @Autowired
    private JwtProperties jwtProperties;

    public JwtAuthenticationTokenFilter() {
        super("/api/secure/**");
    }

    @Override
    public Authentication attemptAuthentication(HttpServletRequest request,
            HttpServletResponse response) {
        String header = request.getHeader(jwtProperties.getJwtHeader());

        if (header == null || !header.startsWith(jwtProperties.getJwtSchema())) {
            throw new JwtTokenMissingException(
                    "No authentication token found in request headers");
        }

        String authToken = header.substring(jwtProperties.getJwtSchema()
                .length());

        JwtAuthenticationToken authRequest = new JwtAuthenticationToken(
                authToken);

        return getAuthenticationManager().authenticate(authRequest);
    }

    @Override
    protected void successfulAuthentication(HttpServletRequest request,
            HttpServletResponse response, FilterChain chain,
            Authentication authResult) throws IOException, ServletException {
        super.successfulAuthentication(request, response, chain, authResult);

        // As this authentication is in HTTP header, after success we need to
        // continue the request normally
        // and return the response as if the resource was not secured at all
        chain.doFilter(request, response);
    }
}

@Component
public class JwtAuthenticationProvider extends  
        AbstractUserDetailsAuthenticationProvider {

    @Autowired
    private JwtTokenValidator jwtTokenValidator;

    @Override
    public boolean supports(Class<?> authentication) {
        return (JwtAuthenticationToken.class.isAssignableFrom(authentication));
    }

    @Override
    protected void additionalAuthenticationChecks(UserDetails userDetails,
            UsernamePasswordAuthenticationToken authentication)
            throws AuthenticationException {
    }

    @Override
    protected UserDetails retrieveUser(String username,
            UsernamePasswordAuthenticationToken authentication)
            throws AuthenticationException {
        JwtAuthenticationToken jwtAuthenticationToken = (JwtAuthenticationToken) authentication;
        String token = jwtAuthenticationToken.getToken();

        CustomUserDetails parsedUser = jwtTokenValidator.parseToken(token);

        if (parsedUser == null) {
            throw new JwtTokenMalformedException("JWT token is not valid");
        }

        return new AuthenticatedUser(parsedUser.getId(),
                parsedUser.getUsername(), token, parsedUser.getAuthorities());
    }

}

JwtAuthenticationEntryPoint and JwtAuthenticationSuccessHandler are straight forward.

The JwtAuthenticationTokenFilter verifies if the request format adheres to the JSON Web Token convention which requires the request Header to look like this:

Authorization Bearer <JSON Web Token>

In this example, we have simply extracted the Authorization and Bearer strings to a properties file.

We will look at the JwtAuthenticationToken class soon, for now we will inspect the JwtAuthenticationProvider. The purpose of this authentication provider is to perform the actual authentication. It takes the JSON Web Token parsed and passed by the JwtAuthenticationTokenFilter and invokes the actual authentication using an injected validator.

The authentication mechanism

The JwtAuthenticationToken only serves to hold the actual token in a way that Spring Security understands:

/**
 * Holder for JWT token from the request.
 * Other fields aren't used but necessary to comply to the contracts of
 * AbstractUserDetailsAuthenticationProvider
 *
 */
public class JwtAuthenticationToken extends UsernamePasswordAuthenticationToken {

    private static final long serialVersionUID = -6181695412034946378L;

    private String token;

    public JwtAuthenticationToken(String token) {
        super(null, null);
        this.token = token;
    }

    public String getToken() {
        return token;
    }

    @Override
    public Object getCredentials() {
        return null;
    }

    @Override
    public Object getPrincipal() {
        return null;
    }
}

Now, let's take a look at the actual JwtTokenValidator:

@Component
public class JwtTokenValidator {

    private static final Logger logger = LoggerFactory
            .getLogger(JwtTokenValidator.class);

    @Autowired
    private JwtProperties jwtProperties;

    @Autowired
    private CredentialsService credentialsService;

    public CustomUserDetails parseToken(String token) {

        CustomUserDetails userDetails = null;

        try {
            Claims body = Jwts.parser()
                    .setSigningKey(jwtProperties.getJwtSecret())
                    .parseClaimsJws(token).getBody();

            // perform credentials check with CredentialsService
        } catch (JwtException e) {
            logger.error("Failed to parse JWT token", e);
        }

        return userDetails;
    }
}

Here, we use the JJWT library to extract the relevant data from the raw JSON Web Token string and then use the CredentialsService to validate the credentials provided in the token. This portion will depend on what data you specify for valid JSON Web Tokens.

Login and token generation mechanism

We have covered the authentication step, however we have not discussed how (valid) tokens are generated in the first step. Recall that we specified the /api/login request path for this:

@RestController
@Transactional
public class WebserviceController {  
    ....
    @Autowired
    private CredentialsService credentialsService;

    @Autowired
    private JwtTokenGenerator jwtTokenGenerator;

    @RequestMapping(value = "/api/login", method = RequestMethod.POST)
    public JwtToken jsonLogin(@RequestBody JwtTokenRequest credentials) {

        JwtToken response = new JwtToken();

        CustomUserDetails userDetails = credentialsService
                .loadUserByUsername(credentials.getUsername());

        if (userDetails == null) {
            response.setError("Bad credentials");
            return response;
        }

        if (credentialsService.verifyCredentials(credentials.getPassword(),
                userDetails.getPassword())) {
            // Generate valid token
            String token = jwtTokenGenerator.generateToken(userDetails.getId(),
                    userDetails.getUsername());
            response.setToken(token);
        } else {
            response.setError("Bad credentials");
        }

        return response;
    }
}

Essentially, we require the user to submit his credentials using a POST request and check these for validity. If all is well, we respond with a valid, freshly generated JSON Web Token. First, let's look at the JwtTokenRequest:

public class JwtTokenRequest {

    private String username;

    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

In this example we require the user to simply pass his username and his password.

If all is well, we use the JwtTokenGenerator to generate a valid JSON Web Token:

@Component
public class JwtTokenGenerator {

    @Autowired
    private JwtProperties jwtProperties;

    public String generateToken(Long id, String username) {

        Claims claims = Jwts.claims().setSubject(username);
        // put further claims as needed

        LocalDateTime oneDayFromNow = LocalDateTime.now().plusHours(
                jwtProperties.getJwtValidHours());
        Date expirationDate = Date.from(oneDayFromNow.atZone(
                (ZoneId.systemDefault())).toInstant());

        return Jwts
                .builder()
                .setClaims(claims)
                .setExpiration(expirationDate)
                .signWith(SignatureAlgorithm.HS512,
                        jwtProperties.getJwtSecret()).compact();
    }
}

Adjust the claims to the data you specified for your JSON Web Tokens. The actual JSON Web Token algorithm is implemented by JJWT. The claims you specify here correspond to the extraction performed in the JwtTokenValidator that we covered earlier.

Finally, the JwtToken POJO that is used to map our response to JSON is again just a holder for the token string:

public class JwtToken {

    private String error;

    private String token;

    public JwtToken() {
    }

    public JwtToken(String token) {
        this.token = token;
    }

    public String getError() {
        return error;
    }

    public void setError(String error) {
        this.error = error;
    }

    public String getToken() {
        return token;
    }

    public void setToken(String token) {
        this.token = token;
    }
}

Conclusion

By combining the JSON Web Token authentication mechanism with Spring Security as demonstrated here, the specified subset of webservice functions can only be used by users who include a valid JSON Web Token in their request headers. Thus, all functions retain their stateless nature. The "statefulness" of the login "state" lies in the validity period of the JSON Web Tokens we generate in JwtTokenGenerator.

Overall, JSON Web Tokens provide a convenient authentication mechanism for webservices that can be integrated into Spring Security with little overhead.

• The web container for our web application (in the example we assume .WAR packaging) deployed to Tomcat
• The db container for our Postgres database
• The db-data container. This one is necessary because Docker containers are volatile by default. Thus, data stored in a container is lost when they are restarted, so we need a volume to permanently store the database data.

Naturally, the applications within their respective containers need to communicate with each other. The current tool of choice to enable inter-container communication is Docker Compose.

Directory and file structure

The directory structure for our Docker files looks like this:

project  
│   docker-compose.yml
│
└───db
    │   Dockerfile
    │
├───web
    │   Dockerfile
    │   application.war

The database container

We will begin with the Dockerfile of our database in ./db/Dockerfile:

FROM postgres:9.4  
MAINTAINER lpradel

ENV POSTGRES_USER admin  
ENV POSTGRES_PASSWORD password  
ENV POSTGRES_DB app_staging  

In this example we are using the standard Postgres 9.4 image and configure credentials for a single user and DB.

The application container

The Dockerfile for our web container in ./web/Dockerfile looks like this:

FROM tomcat:8-jre8  
MAINTAINER lpradel

RUN echo "export JAVA_OPTS=\"-Dapp.env=staging\"" > /usr/local/tomcat/bin/setenv.sh  
COPY ./application.war /usr/local/tomcat/webapps/staging.war

CMD ["catalina.sh", "run"]  

The image is based on the standard Tomcat 8 image. I have included an example of how to perform basic Tomcat configuration. Here, we pass some JAVA_OPTS to the setenv.sh shell script of Tomcat.

Finally, our application .WAR is copied the to the Tomcat webapps directory and deployed in the staging context.

Docker Compose

The last step is orchestrating our containers in ./docker-compose.yml:

app-web:  
  build: ./web
  ports:
    - "8081:8080"
  links:
    - app-db

app-db:  
  build: ./db
  expose:
    - "5432"
  volumes_from:
    - app-db-data

app-db-data:  
  image: cogniteev/echo
  command: echo 'Data Container for PostgreSQL'
  volumes:
    - /var/lib/postgresql/data

We bind the default Tomcat port 8080 in the container to the 8081 port of our host system and expose the Postgres port 5432 to the web container which is linked to it. Lastly, we reference the permanent data volume as a volume for our db container.

Running the application

Execute the following command to start our containers:

$ docker-compose up -d 

To stop the containers run

$ docker-compose stop

A list of all docker containers is available via

$ docker ps -a

To open a shell in one of the containers (for example to access log files), run the following command:

$ docker exec -it <container_id> /bin/bash 

Finally, to redeploy only specific containers, use the following command:

$ docker-compose build <container_id>
$ docker-compose up --no-deps -d <container_id>

Nose: Very light and inoffensive. A bit of sweetness, almost creamy. Borderline indiscriminate.

Colour: Caramel brown.

Taste: Light and sweet (perhaps honey). A tiny bit of sherry. Some lighter fruits.

Finish: Very brief. A bit nutty and rather dry.

Summary: An oddly one-dimensional malt, almost boring. Not for me!

Score: 76/100.

"A man is not dead while his name is still spoken."

^{- Going Postal, Chapter 4}

Nose: Sherry sweetness. Just a tiny bit of peat. Well balanced.

Colour: Light gold.

Taste: Firm body. Less sherry, light and dry. Some malt. Perhaps some dried fruits. Vanilla and some citrus.

Finish: Medium, longer than nose and taste would suggest. Surprisingly spicy with some initial sherry sweetness.

Summary: A pleasant entry-level malt. Glenfarclas has better to offer, although the price is great.

Score: 80/100.

Nose: Plenty of vanilla. Butterscotch. Hints of dried fruits.

Colour: Dark amber.

Taste: Balanced and not at all offensive. Lots of butterscotch. Some apricot. A bit spicy after a few seconds.

Finish: Medium. The caramel lingers for a bit. A bit spicy.

Summary: A decent entry-level bourbon. The price is a little too high.

Score: 78/100.

The SQL/DDL

For the scope of this article I'm assuming a PostgreSQL database.

CREATE TABLE Actor  
(
    actorId serial PRIMARY KEY,
    login character varying(255) UNIQUE NOT NULL,
    password character varying(255) NOT NULL,
    enabled boolean NOT NULL,
    firstName character varying(255),
    lastName character varying(255),
    email character varying(255) NOT NULL,
    created timestamp,
    lastLogin timestamp
);

CREATE TABLE Role  
(
    roleId serial PRIMARY KEY,
    name character varying(255) UNIQUE NOT NULL,
    displayName character varying(255),
    description character varying(255)
);

CREATE TABLE Permission  
(
    permissionId serial PRIMARY KEY,
    name character varying(255) UNIQUE NOT NULL,
    description character varying(255)
);

CREATE TABLE ActorRole  
(
    actorRoleId serial PRIMARY KEY,
    actorId integer REFERENCES Actor,
    roleId integer REFERENCES Role
);

CREATE TABLE RolePermission  
(
    rolePermissionId serial PRIMARY KEY,
    roleId integer REFERENCES Role,
    permissionId integer REFERENCES Permission
);

The custom UserDetails

Expand this class with additional attributes of your Actor entity (e.g. first name, last name, email, address, ...)

public class CustomUserDetails implements UserDetails {

    private static final long serialVersionUID = 9188230014174856593L;

    private String password;
    private final String username;
    private final Set<GrantedAuthority> authorities;
    private final boolean accountNonExpired;
    private final boolean accountNonLocked;
    private final boolean credentialsNonExpired;
    private final boolean enabled;

    public CustomUserDetails (String username, String password,
            Collection<? extends GrantedAuthority> authorities) {
        this(username, password, true, true, true, true, authorities);
    }

    public CustomUserDetails (String username, String password,
            boolean enabled, boolean accountNonExpired,
            boolean credentialsNonExpired, boolean accountNonLocked,
            Collection<? extends GrantedAuthority> authorities) {

        if (((username == null) || "".equals(username)) || (password == null)) {
            throw new IllegalArgumentException(
                    "Cannot pass null or empty values to constructor");
        }

        this.username = username;
        this.password = password;
        this.enabled = enabled;
        this.accountNonExpired = accountNonExpired;
        this.credentialsNonExpired = credentialsNonExpired;
        this.accountNonLocked = accountNonLocked;
        this.authorities = Collections
                .unmodifiableSet(sortAuthorities(authorities));
    }

    private static SortedSet<GrantedAuthority> sortAuthorities(
            Collection<? extends GrantedAuthority> authorities) {
        Assert.notNull(authorities,
                "Cannot pass a null GrantedAuthority collection");
        // Ensure array iteration order is predictable (as per
        // UserDetails.getAuthorities() contract and SEC-717)
        SortedSet<GrantedAuthority> sortedAuthorities = new TreeSet<GrantedAuthority>(
                new AuthorityComparator());

        for (GrantedAuthority grantedAuthority : authorities) {
            Assert.notNull(grantedAuthority,
                    "GrantedAuthority list cannot contain any null elements");
            sortedAuthorities.add(grantedAuthority);
        }

        return sortedAuthorities;
    }

    private static class AuthorityComparator implements
            Comparator<GrantedAuthority>, Serializable {
        private static final long serialVersionUID = SpringSecurityCoreVersion.SERIAL_VERSION_UID;

        public int compare(GrantedAuthority g1, GrantedAuthority g2) {
            // Neither should ever be null as each entry is checked before
            // adding it to
            // the set.
            // If the authority is null, it is a custom authority and should
            // precede
            // others.
            if (g2.getAuthority() == null) {
                return -1;
            }

            if (g1.getAuthority() == null) {
                return 1;
            }

            return g1.getAuthority().compareTo(g2.getAuthority());
        }
    }

    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return authorities;
    }

    @Override
    public String getPassword() {
        return password;
    }

    @Override
    public String getUsername() {
        return username;
    }

    @Override
    public boolean isAccountNonExpired() {
        return accountNonExpired;
    }

    @Override
    public boolean isAccountNonLocked() {
        return accountNonLocked;
    }

    @Override
    public boolean isCredentialsNonExpired() {
        return credentialsNonExpired;
    }

    @Override
    public boolean isEnabled() {
        return enabled;
    }
}

The custom UserDetailsService

Adapt the loadUserByUsername method to feed the additional custom actor entity attributes to the CustomUserDetails object.

@Service
@Transactional(readOnly = true)
public class CustomUserDetailsService implements UserDetailsService {

    @Autowired
    private ActorRepository actorRepository;

    @Override
    public UserDetails loadUserByUsername(String username)
            throws UsernameNotFoundException {

        try {
            Actor actor = actorRepository.findByLogin(username);

            boolean enabled = true;
            boolean accountNonExpired = true;
            boolean credentialsNonExpired = true;
            boolean accountNonLocked = true;

            // adapt as needed
            return new CustomUserDetails(actor.getLogin(),
                    actor.getPassword(), enabled, accountNonExpired,
                    credentialsNonExpired, accountNonLocked,
                    getAuthorities(actor.getRoles()));

        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    private static class SimpleGrantedAuthorityComparator implements
            Comparator<SimpleGrantedAuthority> {

        @Override
        public int compare(SimpleGrantedAuthority o1, SimpleGrantedAuthority o2) {
            return o1.equals(o2) ? 0 : -1;
        }
    }

    /**
     * Retrieves a collection of {@link GrantedAuthority} based on a list of
     * roles
     * 
     * @param roles
     *            the assigned roles of the user
     * @return a collection of {@link GrantedAuthority}
     */
    public Collection<? extends GrantedAuthority> getAuthorities(Set<Role> roles) {

        Set<SimpleGrantedAuthority> authList = new TreeSet<SimpleGrantedAuthority>(
                new SimpleGrantedAuthorityComparator());

        for (Role role : roles) {
            authList.addAll(getGrantedAuthorities(role));
        }

        return authList;
    }

    /**
     * Wraps a {@link Role} role to {@link SimpleGrantedAuthority} objects
     * 
     * @param roles
     *            {@link String} of roles
     * @return list of granted authorities
     */
    public static Set<SimpleGrantedAuthority> getGrantedAuthorities(Role role) {

        Set<SimpleGrantedAuthority> authorities = new HashSet<SimpleGrantedAuthority>();

        Set<Permission> rolePermissions = role.getPermissions();
        for (Permission permission : rolePermissions) {
            authorities.add(new SimpleGrantedAuthority(permission.getName()));
        }

        return authorities;
    }
}

The Spring configuration

In this example I'm using XML to configure Spring Security. Naturally this can also be done using annotations.

<beans:beans xmlns="http://www.springframework.org/schema/security"  
    xmlns:beans="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
    http://www.springframework.org/schema/security
    http://www.springframework.org/schema/security/spring-security.xsd">

    <http auto-config="true" authentication-manager-ref="adminAuthMgr">
        <intercept-url pattern="/admin/**"
            access="hasAuthority('PERM_ACCESS_ADMIN_AREA')" />

        <form-login login-page="/login" default-target-url="/admin/dashboard"
            authentication-failure-url="/login?error"
            username-parameter="username" password-parameter="password"
            login-processing-url="/j_spring_security_check" />
        <logout logout-url="/j_spring_security_logout"
            logout-success-url="/login?logout" />
        <csrf />
    </http>

    <authentication-manager alias="adminAuthMgr">
        <authentication-provider
            user-service-ref="customUserDetailsService">
            <password-encoder hash="bcrypt" />
        </authentication-provider>
    </authentication-manager>
</beans:beans>  

Remarks

Note how you can use the hasAuthority(PERM_XY) or hasAuthority(ROLE_ZY) expression to elegantly handle that both permissions from the Permission table and roles from the Role table are stored in the permissions attribute of Spring UserDetails.

Nose: Alcoholic. Tingling and slightly stinging. Some malt, good chunk of sherry. A good bit of oak, and some honey. Adding some water definitely opens up the nose and helps with the slightly unpleasant alcohol.

Colour: Dark amber. Uncolored according to label.

Taste: Full and heavy. Rather dry. Initially some dried or toasted fruits and more honey. Malty. Then, sherry big time. Very full-bodied. Extremely spicy, even with water.

Finish: Medium. Lots of sherry and heavy oak to the point of bitterness. Very dry.

Summary: Certainly not a bad dram, but not my cup of whisky. My first sherried whisky. Can't say that I'm too much of a fan of this, although I have no doubt that this is a quality dram. YMMV.

Score: 72/100.

To achieve this we must add an artificial value to our enum. For this, we use PowerMock and Mockito. Consider the following enum:

public enum Day {  
    MONDAY, FRIDAY 
}

Now, suppose an instance of Day is evaluated in the following method using a switch statement:

public void tellItLikeItIs(Day day) {  
    switch (day) {
        case MONDAY:
            System.out.println("Mondays are bad.");
            break;

        case FRIDAY:
            System.out.println("Fridays are better.");
            break;

        default:
            System.out.println("The other days are so-so.");
            break;
    }
}

In the current state of the Day enum, all cases are covered and the default statement is not executed. However we might want to ensure correct behaviour in the default case using a unit test in case other days are added later.

We implement our testing strategy as follows:

@PrepareForTest(Day.class)
public class DayTest extends BaseTest {

    @Mock
    private Day additionalDay;

    @Test
    public void testTellItLikeItIsDefaultCase()
    {
        Day[] values = Day.values();
        Day[] valuesAndAdditional = new Day[values.length + 1];
        System.arraycopy(values, 0, valuesAndAdditional, 0, values.length);

        // create additional, artificial Day
        PowerMockito.mockStatic(Day.class);

        Whitebox.setInternalState(additionalDay, "name", "ADDITIONAL_DAY");
        Whitebox.setInternalState(additionalDay, "ordinal", values.length);
        valuesAndAdditional[values.length] = additionalDay;

        when(Day.values()).thenReturn(
                valuesAndAdditional);

        tellItLikeItIs(additionalDay);

        // Tests for default case behaviour
        // ...
    }

Note that we need to annotate our Test with PrepareForTest bound to our enum, as we perform a static mock on it later. For our mocked enum value, we set the name and ordinal attributes accordingly as these are evaluated in the switch statement. Finally, we overwrite the return value of the values method of our enum to include the additional value.

Note that at this point in time there appears to be a bug in PowerMock which allows for correct mocking only when the enum-related method is executed first in the test class!

Ensuring that the method in question is executed first depends on your specific testing framework.

Booting and graphics rendering

At the time of this blog post the current version of the nouveau driver does not support the GeForce GTX970M/GTX980M. This will change in the future. Refer to nouveau's feature matrix for the current state of card support.

For this reason it is necessary to disable the auto-loading of the nouveau driver by modern Linux kernels upon boot. Otherwise you will only get a blank screen. To do this, press e in the Arch boot menu and append the following:

nomodeset  

This will force Linux to use software graphics rendering instead of using the nouveau driver. Your machine has powerful hardware so you will have no further issues with this during installation.

Installation

The installation process is no different than on any other machine. You can follow the Installation guide from the wiki.

Bootloader

The G75x devices boot using UEFI rather than MBR. In my experience using gummiboot or rEFInd will give you the least hassle to get your bootloader up and running, especially if you are going for a dual-boot setup like I did. Both will automatically detect your Windows bootloader and add a correct boot menu entry. I find GRUB to be rather complicated to configure correctly for UEFI but the choice is yours.

Graphics driver and kernel compilation

I strongly recommend using the proprietary NVIDIA drivers. Furthermore I needed to either keep using the nomodeset in the kernel parameters of my bootloader or recompiling the kernel with the parameter. I went for the latter option. Edit your /etc/mkinitcpio.conf file with the editor of your choice to include the nomodeset parameter and then recompile using the following command:

# mkinitcpio -p linux

Keyboard backlight

For me, the keyboard backlight was disabled/off out of the box. You can use the appropriate multimedia keys to manipulate the backlight or install the asus-kbd-backlight package for control from the command line. Install the package from the AUR and hook it into systemd:

# systemctl daemon-reload
# systemctl start asus-kbd-backlight.service
# systemctl enable asus-kbd-backlight.service

Usage is very straight-forward:

$ asus-kbd-backlight up
$ asus-kbd-backlight down
$ asus-kbd-backlight max
$ asus-kbd-backlight off
$ asus-kbd-backlight night
$ asus-kbd-backlight 2
$ asus-kbd-backlight show

Presentations

I suppose this is more of a general Arch laptop issue but I figured it might be interesting to some folks. Install the xorg-xrandr package or use graphical packages like arandr. Check the docs of the packages for further info.

Final remarks

The trackpad works out of the box with the newer Linux kernels. Have fun running Arch on your ASUS G75x!

Nose: Pleasant earthiness. Heather. Some malt, hints of sherry.

Colour: Dark gold.

Taste: Some initial sherry. Very smooth. Heather-honey sweetness. Pineapple. Ever so gentle smoke. Delicious.

Finish: Medium. Glorious Highland Park peat. Very dry.

Summary: A great dram! Reasonably complex and incredibly well-balanced bit of everything. The HP smoke is extraordinary!

Score: 88/100.

• gcc
• clang
• autotools
• make
• cmake
• scons

Using these is very straight forward. An example .travis.yml file for CMake projects looks like this:

language: cpp

compiler:  
    - gcc
    - clang

before_script:  
    - mkdir build
    - cd build
    - cmake ..

script: make  

We specify C++ as our language compiling with both gcc and clang. We create the standard CMake build directory and execute the cmake command in our project's home directory. Finally, we invoke make on the auto-generated Makefiles.

Using scons actually looks very similar to this: we just omit the cmake invocation and replace the script line with the following:

script: scons  

Configuring Tomcat

In order to access MBeans remotely, some configuration^[1] is required. Tomcat provides a number of system arguments that can be used to enable remote JMX access. As with all Tomcat configuration, the following is best placed in $TOMCAT_ROOT/bin/setenv.sh:

-Dcom.sun.management.jmxremote 
-Dcom.sun.management.jmxremote.port=%YOUR_JMX_PORT% 
-Dcom.sun.management.jmxremote.authenticate=false 
-Dcom.sun.management.jmxremote.ssl=false

This allows anyone to remotely connect to your Tomcat's MBeans.

If you require secured access, consider the following:

-Dcom.sun.management.jmxremote 
-Dcom.sun.management.jmxremote.port=%YOUR_JMX_PORT% 
-Dcom.sun.management.jmxremote.authenticate=true 
-Dcom.sun.management.jmxremote.ssl=false
-Djava.rmi.server.hostname=%IP address whitelist%
-Dcom.sun.management.jmxremote.password.file=../conf/jmxremote.password
-Dcom.sun.management.jmxremote.access.file=../conf/jmxremote.access

User access is managed in $TOMCAT_ROOT/conf/jmxremote.access:

monitorRole readonly  
controlRole readwrite  

And finally, the passwords are stored in $TOMCAT_ROOT/conf/jmxremote.password:

monitorRole tomcat-jmx-pw  
controlRole tomcat-jmx-pw2  

Registering MBeans

The easiest way of registering and unregistering your MBeans is by using a dedicated ServletContextListener whose sole purpose is to take care of your MBeans:

package com.lukaspradel.example.servlet;

import org.slf4j.Logger;  
import org.slf4j.LoggerFactory;

import javax.management.InstanceAlreadyExistsException;  
import javax.management.InstanceNotFoundException;  
import javax.management.MBeanRegistrationException;  
import javax.management.MBeanServer;  
import javax.management.MalformedObjectNameException;  
import javax.management.NotCompliantMBeanException;  
import javax.management.ObjectName;  
import javax.servlet.ServletContext;  
import javax.servlet.ServletContextEvent;  
import javax.servlet.ServletContextListener;  
import javax.servlet.annotation.WebListener;

import java.lang.management.ManagementFactory;

@WebListener
public class MBeanContextListener implements ServletContextListener {

    private static final Logger LOG = LoggerFactory.getLogger(MBeanContextListener.class);

    private ObjectName exampleManagementObjectName;

    @Override
    public void contextInitialized(final ServletContextEvent sce) {

        LOG.debug("Register MBeans..");

        final MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();

        try {
            exampleManagementObjectName = new ObjectName("com.lukaspradel.example.management:type=ExampleManagement");
            final ExampleManagement examleMbean = new ExampleManagement();
            mbeanServer.registerMBean(examleMbean, exampleManagementObjectName);
        } catch (InstanceAlreadyExistsException | MalformedObjectNameException | MBeanRegistrationException | NotCompliantMBeanException e) {
            LOG.error("Failed to register MBeans!", e);
        }
    }

    @Override
    public void contextDestroyed(final ServletContextEvent sce) {

        LOG.debug("Unregister MBeans..");

        final MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();

        try {
            mbeanServer.unregisterMBean(exampleManagementObjectName);
        } catch (MBeanRegistrationException | InstanceNotFoundException e) {
            LOG.error("Failed to unregister MBeans!", e);
        }
    }
}

The callback functions defined by ServletContextListener provide excellent access points for registering and unregistering our MBeans. The boilerplate for the actual MBean handling is plain JMX and very straight-forward.

Calling MBeans

A central MBeanInvoker will serve for demonstration purposes on how to remotely invoke MBean methods.

package com.lukaspradel.example.management;

import org.slf4j.Logger;  
import org.slf4j.LoggerFactory;

import javax.enterprise.context.ApplicationScoped;  
import javax.management.JMX;  
import javax.management.MBeanServerConnection;  
import javax.management.ObjectName;  
import javax.management.remote.JMXConnector;  
import javax.management.remote.JMXConnectorFactory;  
import javax.management.remote.JMXServiceURL;

@ApplicationScoped
public class MBeanInvoker {

    private static final Logger LOG = LoggerFactory.getLogger(MBeanInvoker.class);

    private static final String JMX_URL = "service:jmx:rmi:///jndi/rmi://localhost:9012/jmxrmi";

    private static final String MBEAN_EXAMPLE_MANAGEMENT = "com.lukaspradel.example.management:type=ExampleManagement";

    private MBeanServerConnection mbsc;

    @PostConstruct
    public void init() {

        try {
            JMXServiceURL url = new JMXServiceURL(JMX_URL);
            JMXConnector jmxc = JMXConnectorFactory.connect(url, null);

            mbsc = jmxc.getMBeanServerConnection();
        } catch (Exception e) {
            LOG.error("Failed to initialize MBeanInvoker!", e);
        }
    }

    public String invokeExampleMBeanExampleMethod(String arg1) throws Exception {

        ObjectName exampleMBeanName = new ObjectName(MBEAN_SESSION_MANAGEMENT);
        ExampleManagementMBean exampleManagementMBean = JMX.newMXBeanProxy(mbsc, exampleMBeanName, ExampleManagementMBean.class, true);

        // not type-safe method
        // Object result = mbsc.invoke(exampleMBeanName, "exampleMethod", new Object[] {arg1}, new String[] {"java.lang.String"});

        String result = exampleManagementMBean.exampleMethod(arg1);

        return result;
    }
}

Again, the code is very straight-forward and self-explaining. We use plain JMX to create an MBeanServerConnection to our correctly configured Tomcat running as localhost at JMX port 9012. What makes JMX truly great is that we can invoke the remote MBeans type-safe using their interfaces. Alternatively, reflection-esque method calling is also supported.

Final remarks

You can manually invoke your MBean methods for testing purposes using the J2SE tool jconsole. Connect to your Tomcat's JMX port by choosing "Remote process" and entering for example localhost:9012. Aside from the tab "MBeans" where you can manually invoke methods with arguments, you will also see other monitoring information like memory usage, Thread info and a JVM summary.

^{1. http://tomcat.apache.org/tomcat-7.0-doc/monitoring.html↩}

In this article I will demonstrate an alternative technique which involves integration testing as part of your build pipeline using the Maven Cargo plugin ^[1]. The idea is to hook into the integration-test phase of the Maven Failsafe plugin which is by Maven convention the gateway to integration testing in the Maven lifecycle.

The setting that will serve as an example is as follows: our web application is built to a single WAR artifact that is deployed to a Tomcat servlet container. It is configured by properties files in a configuration directory outside of the application context. The location of the configuration directory is supplied by passing a JVM argument to the Tomcat instance.

Integrating automated container deployment

We begin by adding a dedicated profile for integration testing purposes. This can be useful to control when to perform integration tests as they tend to consume a lot more time than smoke tests or unit tests.

    <profiles>
        <profile>
            <id>integration-test</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <artifactId>maven-failsafe-plugin</artifactId>
                    </plugin>
                    <plugin>
                        <groupId>org.codehaus.cargo</groupId>
                        <artifactId>cargo-maven2-plugin</artifactId>
                        <version>${cargo.plugin.version}</version>
                        <configuration>
                            <container>
                                <containerId>tomcat7x</containerId>
                                <zipUrlInstaller>
                                    <url>http://archive.apache.org/dist/tomcat/tomcat-7/v7.0.54/bin/apache-tomcat-7.0.54.zip</url>
                                    <downloadDir>${project.build.directory}/downloads</downloadDir>
                                    <extractDir>${project.build.directory}/extracts</extractDir>
                                </zipUrlInstaller>
                            </container>
                            <deployables>
                                <deployable>
                                    <properties>
                                        <context>ROOT</context>
                                    </properties>
                                </deployable>
                            </deployables>
                            <configuration>
                                <configfiles>
                                    <configfile>
                                        <file>${cargo.container.configuration.src.dir}/config1.properties</file>
                                        <todir>${cargo.container.configuration.to.dir}</todir>
                                    </configfile>
                                    <configfile>
                                        <file>${cargo.container.configuration.src.dir}/config2.properties</file>
                                        <todir>${cargo.container.configuration.to.dir}</todir>
                                    </configfile>
                                </configfiles>
                            </configuration>
                        </configuration>
                        <executions>
                            <execution>
                                <id>start-tomcat</id>
                                <phase>pre-integration-test</phase>
                                <goals>
                                    <goal>start</goal>
                                </goals>
                                <configuration>
                                    <configuration>
                                        <properties>
                                            <cargo.jvmargs>${cargo.container.jvmargs}</cargo.jvmargs>
                                        </properties>
                                    </configuration>
                                </configuration>
                            </execution>
                            <execution>
                                <id>stop-tomcat</id>
                                <phase>post-integration-test</phase>
                                <goals>
                                    <goal>stop</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>

We begin by configuring the Maven Failsafe plugin and further use the Cargo plugin whose executions we bind to the pre-integration-test and post-integration-test phases respectively. The idea is to start the Tomcat during pre-integration-test and deploy our application and to gracefully shutdown the Tomcat during post-integration-test.

Firstly, we configure one or more containers. In this case we need only a Tomcat which we download directly from the Apache archive to target/downloads and extract it to target/extracts. Our deployable WAR artifact is deployed as ROOT in this example. The configfiles property is used to manually copy external artifacts into the application context. Finally, we can configure JVM arguments in the pre-integration-test phase by configuring the cargo.jvmargs property.

For reference, the properties section of our POM looks like this:

<properties>  
...
        <cargo.plugin.version>1.4.9</cargo.plugin.version>
        <cargo.container.configuration.src.dir>${basedir}/../configuration-test/src/main/resources/com/lukaspradel/example/configuration/test</cargo.container.configuration.src.dir>
        <cargo.container.configuration.to.dir>conf/properties/test</cargo.container.configuration.to.dir>
        <cargo.container.jvmargs>-D.configuration.dir=${cargo.container.configuration.to.dir}
            -Dcom.sun.management.jmxremote
            -Dcom.sun.management.jmxremote.port=9012
            -Dcom.sun.management.jmxremote.authenticate=false
            -Dcom.sun.management.jmxremote.ssl=false</cargo.container.jvmargs>
...
</properties>  

This integrates automatic setup of a container as well as deployment of our application to said container into our build pipeline. A list of supported containers can be found in the documentation of the Cargo plugin. All common containers are supported such as

• Geronimo
• Glassfish
• JBoss
• Jetty
• Tomcat
• WebLogic
• WebSphere
• Wildfly

Take a look at the official doc ^[2].

Basic smoke testing

By convention, all unit test classes whose names end with IT are considered integration tests by the Maven failsafe plugin. Hence, no further configuration is necessary, unless you wish to differentiate them further.

As a basic integration smoke test we will check if our application is deployed successfully and the Tomcat serves with HTTP code OK (200). An easy to use HTTPClient is the Apache httpclient:

<dependencies>  
...
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpclient</artifactId>
            <version>${httpclient.version}</version>
            <scope>test</scope>
        </dependency>
...
</dependencies>  

Our smoke test looks as follows:

package com.lukaspradel.example.it;

import com.lukaspradel.example.it.common.AbstractIntegrationTest;  
import org.apache.http.HttpResponse;  
import org.apache.http.HttpStatus;  
import org.apache.http.client.ClientProtocolException;  
import org.apache.http.client.CookieStore;  
import org.apache.http.client.HttpClient;  
import org.apache.http.client.methods.HttpGet;  
import org.apache.http.client.protocol.HttpClientContext;  
import org.apache.http.impl.client.BasicCookieStore;  
import org.apache.http.impl.client.HttpClientBuilder;  
import org.testng.annotations.Test;

import java.io.IOException;

import static org.testng.Assert.assertEquals;

/**
 * Check if the application was deployed correctly during integration-test phase
 * and if it can be reached successfully.
 *
 * @author pradel
 *
 */
public class CheckApplicationDeploymentIT extends AbstractIntegrationTest {

    @Test
    public void testWebapplicationUp() throws ClientProtocolException, IOException {

        HttpClient client = HttpClientBuilder.create().build();
        CookieStore cookieStore = new BasicCookieStore();
        HttpClientContext context = HttpClientContext.create();
        context.setCookieStore(cookieStore);

        HttpGet httpget = new HttpGet(BASE_URL);

        HttpResponse response = client.execute(httpget, context);

        assertEquals(response.getStatusLine().getStatusCode(), HttpStatus.SC_OK);
    }
}

Here, we assume that AbstractIntegrationTest supplies something like
protected static final String BASE_URL = "http://localhost/";.

<sup>1. http://cargo.codehaus.org/Home↩
2. http://cargo.codehaus.org/Containers↩</sup>

Nose: Very dominant malt. Strong toffee. Some citrus. A bit of sweetness yet kind of alcoholic.

Colour: Darker amber.

Taste: Oily body. Very malty. Lots of toffee. Some dark fruits. A distinct touch of oak. Hints of lemons.

Finish: Very short. Dangerously quaffable. A bit woody. Surprisingly bitter. Leaves a bitter taste of tobacco after a few minutes.

Summary: An average dram. By no means bad but certainly not exceptional either. A good deal for the very low price.

Score: 73/100.