cjmx: A command-line version of JConsole
JConsole is a nice tool when it comes to monitoring a running Java application. But when it is not possible to connect to a JVM with JConsole directly (due to network restrictions for example) and SSH tunneling is not possible, then it would be great to have a command line version of JConsole.
jcmx is such a command line version of JConsole. After having downloaded the single jar file cjmx_2.10-2.1.0-app.jar you can start it by including the tools.jar into the classpath:
java -cp $JAVA_HOME/lib/tools.jar:cjmx_2.10-2.1.0-app.jar cjmx.Main
This will open a “JMX shell” with the following basic commands:
- help: This shows a basic help screen that explains the available commands.
- jps/list: Like the jps tool from the JDK this command prints out all java processes with their process id.
- connect: You can use this command to connect to a running JVM process.
- format: Let’s you specify whether you want your output in a simple text format or as a JSON string.
- exit: Quits the application.
To learn more about cjmx let us start a session and connect to the JVM that is running cjmx itself:
> jps 13198 cjmx.Main > connect 13198 Connected to local virtual machine 13198 Connection id: rmi://0:0:0:0:0:0:0:1 2 Default domain: DefaultDomain 5 domains registered consisting of 19 total MBeans > describe disconnect exit format help invoke mbeans names names sample select status
After the last appearance of > you see a great feature of cjmx: auto-completion. Every time you do not know which commands are available, you can just type [TAB] and cjmx will list them. This even works for MBean names as we will see.
Now that we are connected to our JVM we can let cjmx describe an available MBean. With auto-completion we can just start typing describe '[TAB] to retrieve a list of all available packages:
> describe ' : JMImplementation: com.sun.management: java.lang: java.nio: java.util.logging:
This way we can dig through the MBean names until we have found what we are looking for. In this example we are interested in the MBean ‘java.lang:type=OperatingSystem’:
> describe 'java.lang:type=OperatingSystem' Object name: java.lang:type=OperatingSystem ------------------------------------------- Description: Information on the management interface of the MBean Attributes: MaxFileDescriptorCount: long OpenFileDescriptorCount: long FreePhysicalMemorySize: long CommittedVirtualMemorySize: long FreeSwapSpaceSize: long ProcessCpuLoad: double ProcessCpuTime: long SystemCpuLoad: double TotalPhysicalMemorySize: long TotalSwapSpaceSize: long AvailableProcessors: int Arch: String SystemLoadAverage: double Name: String Version: String ObjectName: ObjectName
As we can see, the MBean ‘java.lang:type=OperatingSystem’ provides information about the number of open files and the current CPU load, etc.. So let’s query the number of open files by invoking the command mbeans with the name of the MBean as well as the sub-command select and the MBean’s attribute:
> mbeans 'java.lang:type=OperatingSystem' select OpenFileDescriptorCount java.lang:type=OperatingSystem ------------------------------ OpenFileDescriptorCount: 35
We can even query all available attributes by using the star instead of the concrete name of an attribute. Please note that using the cursor up key recalls the last issued command, hence we do not have to type it again. Instead we just replace the attribute’s name with the star:
> mbeans 'java.lang:type=OperatingSystem' select * java.lang:type=OperatingSystem ------------------------------ MaxFileDescriptorCount: 10240 OpenFileDescriptorCount: 36 ...
By using the sub-command invoke we can even invoke MBean methods like in the following example:
> mbeans 'java.lang:type=Memory' invoke gc() java.lang:type=Memory: null
Now that we know how to query attributes and invoke methods, we can start to script this functionality in order to monitor the application. To support this kind of scripting, cjmx provides the feature that one can pass all “commands” also as an argument to the application itself, hence you can invoke cjmx in the following way (where <PID> has to be replaced by a concrete process id of a running JVM):
java -cp $JAVA_HOME/lib/tools.jar:cjmx_2.10-2.1.0-app.jar cjmx.Main &amp;lt;PID&amp;gt; &amp;quot;mbeans 'java.lang:type=OperatingSystem' select OpenFileDescriptorCount&amp;quot; java.lang:type=OperatingSystem ------------------------------ OpenFileDescriptorCount: 630
With this knowledge we can write a simple bash script that queries the JVM each second for the number of open files:
#!/bin/bash
while [ true ] ; do
echo `date` | tr -d '\n'
java -cp /usr/java/default/lib/tools.jar:cjmx_2.10-2.1.0-app.jar cjmx.Main $1 &amp;quot;mbeans 'java.lang:type=OperatingSystem' select OpenFileDescriptorCount&amp;quot;|grep OpenFileDescriptorCount|cut -f 2 -d :
sleep 1
done
This produces each second a new line with a timestamp and the the current number of open files. When redirected into a file, we have a simple log file and can evaluate it later on.
Conclusion: cjmx is a great alternative to JConsole when the latter cannot be used due to network restrictions on a server machine. The ability to even issue commands by passing them on the command line makes it suitable for small monitoring scripts.
Analysing the performance degradation/improvements of a Java EE application with interceptors
When you are developing a Java EE application with certain performance requirements, you have to verify that these requirements are fulfilled before each release. An Hudson job that nightly executes a bunch of test measurements on some specific hardware platform is what you may think about.
You can check the achieved timings and compare them with the given requirements. If the measured values deviate from the requirements too much, you can either break the build or at least send an email to the team.
But how do you measure the execution time of your code? The very first thought might be to add thousands of insertions of time measuring code into your code base. But this is not only a lot of work, but also has an impact on the performance of your code, as now the time measurements are also executed in production. To get rid of the many insertions you might want to leverage an aspect oriented framework (AOP) that introduces the code for time measurements at compile time. Using this way you have at least two versions of your application: the one with and the one without the additional overhead. To measure performance at some production site still requires a redeployment of your code. And you have to decide which methods you want to observe already at compile time.
Java EE comes therefore with an easy to use alternative: Interceptors. This is were the inversion of control pattern plays out its advantages. As the Application Server invokes your bean methods/web service calls, it is easy for it to intercept these invocations and provide you a way of adding code before and after each invocation.
Using interceptors is then fairly easy. You can either add an annotation to your target method or class that references your interceptor implementation or you can add the interceptor using the deployment descriptor:
@Interceptors(PerformanceInterceptor.class)
public class CustomerService {
...
}
The same information supplied in the deployment descriptor looks like this:
<interceptor-binding>
<target-name>myapp.CustomerService</target-name>
<interceptor-class>myapp.PerformanceInterceptor.class</interceptor-class>
</interceptor-binding>
The interceptor itself can be a simple POJO class with a method that is annotated with @AroundInvoke and one argument:
@AroundInvoke
public Object measureExecutionTime(InvocationContext ctx) throws Exception {
long start = System.currentTimeMillis();
try {
return ctx.proceed();
} finally {
long time = System.currentTimeMillis() - start;
Method method = ctx.getMethod();
RingStorage ringStorage = RingStorageFactory.getRingStorage(method);
ringStorage.addMeasurement(time);
}
}
Before the try block and in the finally block we add our code for the time measurement. As can be seen from the code above, we also need some in-memory location where we can store the last measurement values in order to compute for example a mean value and the deviation from the mean value. In this example we have a simple ring storage implementation that overrides old values after some time.
But how to expose these values to the world outside? As many other values of the Application Server are exposed over the JMX interface, we can implement a simple MXBean interface like shown in the following code snippet:
public interface PerformanceResourceMXBean {
long getMeanValue();
}
public class RingStorage implements PerformanceResourceMXBean {
private String id;
public RingStorage(String id) {
this.id = id;
registerMBean();
...
}
private void registerMBean() {
try {
ObjectName objectName = new ObjectName("performance" + id + ":type=" + this.getClass().getName());
MBeanServer platformMBeanServer = ManagementFactory.getPlatformMBeanServer();
try {
platformMBeanServer.unregisterMBean(objectName);
} catch (Exception e) {
}
platformMBeanServer.registerMBean(this, objectName);
} catch (Exception e) {
throw new IllegalStateException("Problem during registration:" + e);
}
}
@Override
public long getMeanValue() {
...
}
...
}
Now we can start the jconsole and query the exposed MXBean for the mean value:
Writing a small JMX client application that writes the sampled values for example into a CSV file, enables you to later on process these values and compare them with later measurements. This gives you an overview of the evolution of your application’s performance.
Conclusion: Adding dynamically through the deployment descriptor performance measurement capabilities to an existing Java EE application is with the use of interceptors easy. If you expose the measured values over JMX, you can apply further processing of the values afterwards.
Using @NamedEntityGraph to load JPA entities more selectively in N+1 scenarios
The N+1 problem is a common issue when working with ORM solutions. It happens when you set the fetchType for some @OneToMany relation to lazy, in order to load the child entities only when the Set/List is accessed. Let’s assume we have a Customer entity with two relations: a set of orders and a set of addresses for each customer.
@OneToMany(mappedBy = "customer", cascade = CascadeType.ALL, fetch = FetchType.LAZY) private Set<OrderEntity> orders; @OneToMany(mappedBy = "customer", cascade = CascadeType.ALL, fetch = FetchType.LAZY) private Set<AddressEntity> addresses;
To load all customers, we can issue the following JPQL statement and afterwards load all orders for each customer:
List<CustomerEntity> resultList = entityManager.createQuery("SELECT c FROM CustomerEntity AS c", CustomerEntity.class).getResultList();
for(CustomerEntity customerEntity : resultList) {
Set<OrderEntity> orders = customerEntity.getOrders();
for(OrderEntity orderEntity : orders) {
...
}
}
Hibernate 4.3.5 (as shipped with JBoss AS Wildfly 8.1.0CR2) will generate the following series of SQL statements out of it for only two(!) customers in the database:
Hibernate:
select
customeren0_.id as id1_1_,
customeren0_.name as name2_1_,
customeren0_.numberOfPurchases as numberOf3_1_
from
CustomerEntity customeren0_
Hibernate:
select
orders0_.CUSTOMER_ID as CUSTOMER4_1_0_,
orders0_.id as id1_2_0_,
orders0_.id as id1_2_1_,
orders0_.campaignId as campaign2_2_1_,
orders0_.CUSTOMER_ID as CUSTOMER4_2_1_,
orders0_.timestamp as timestam3_2_1_
from
OrderEntity orders0_
where
orders0_.CUSTOMER_ID=?
Hibernate:
select
orders0_.CUSTOMER_ID as CUSTOMER4_1_0_,
orders0_.id as id1_2_0_,
orders0_.id as id1_2_1_,
orders0_.campaignId as campaign2_2_1_,
orders0_.CUSTOMER_ID as CUSTOMER4_2_1_,
orders0_.timestamp as timestam3_2_1_
from
OrderEntity orders0_
where
orders0_.CUSTOMER_ID=?
As we can see, the first query selects all customers from the table CustomerEntity. The following two selects fetch then the orders for each customer we have loaded in the first query. When we have 100 customers instead of two, we will get 101 queries. One initial query to load all customers and then for each of the 100 customers an additional query for the orders. That is the reason why this problem is called N+1.
A common idiom to solve this problem is to force the ORM to generate an inner join query. In JPQL this can be done by using the JOIN FETCH clause like demonstrated in the following code snippet:
entityManager.createQuery("SELECT c FROM CustomerEntity AS c JOIN FETCH c.orders AS o", CustomerEntity.class).getResultList();
As expected the ORM now generates an inner join with the OrderEntity table and therewith only needs one SQL statement to load all data:
select
customeren0_.id as id1_0_0_,
orders1_.id as id1_1_1_,
customeren0_.name as name2_0_0_,
orders1_.campaignId as campaign2_1_1_,
orders1_.CUSTOMER_ID as CUSTOMER4_1_1_,
orders1_.timestamp as timestam3_1_1_,
orders1_.CUSTOMER_ID as CUSTOMER4_0_0__,
orders1_.id as id1_1_0__
from
CustomerEntity customeren0_
inner join
OrderEntity orders1_
on customeren0_.id=orders1_.CUSTOMER_ID
In situations where you know that you will have to load all orders for each customer, the JOIN FETCH clause minimizes the number of SQL statements from N+1 to 1. This comes of course with the drawback that you now transfer for all orders of one customer the customer data again and again (due to the additional customer columns in the query).
The JPA specification introduces with version 2.1 so called NamedEntityGraphs. This annotation lets you describe the graph a JPQL query should load in more detail than a JOIN FETCH clause can do and therewith is another solution to the N+1 problem. The following example demonstrates a NamedEntityGraph for our customer entity that is supposed to load only the name of the customer and its orders. The orders are described in the subgraph ordersGraph in more detail. Here we see that we only want to load the fields id and campaignId of the order.
@NamedEntityGraph(
name = "CustomersWithOrderId",
attributeNodes = {
@NamedAttributeNode(value = "name"),
@NamedAttributeNode(value = "orders", subgraph = "ordersGraph")
},
subgraphs = {
@NamedSubgraph(
name = "ordersGraph",
attributeNodes = {
@NamedAttributeNode(value = "id"),
@NamedAttributeNode(value = "campaignId")
}
)
}
)
The NamedEntityGraph is given as a hint to the JPQL query, after it has been loaded via EntityManager using its name:
EntityGraph entityGraph = entityManager.getEntityGraph("CustomersWithOrderId");
entityManager.createQuery("SELECT c FROM CustomerEntity AS c", CustomerEntity.class).setHint("javax.persistence.fetchgraph", entityGraph).getResultList();
Hibernate supports the @NamedEntityGraph annotation since version 4.3.0.CR1 and creates the following SQL statement for the JPQL query shown above:
Hibernate:
select
customeren0_.id as id1_1_0_,
orders1_.id as id1_2_1_,
customeren0_.name as name2_1_0_,
customeren0_.numberOfPurchases as numberOf3_1_0_,
orders1_.campaignId as campaign2_2_1_,
orders1_.CUSTOMER_ID as CUSTOMER4_2_1_,
orders1_.timestamp as timestam3_2_1_,
orders1_.CUSTOMER_ID as CUSTOMER4_1_0__,
orders1_.id as id1_2_0__
from
CustomerEntity customeren0_
left outer join
OrderEntity orders1_
on customeren0_.id=orders1_.CUSTOMER_ID
We see that Hibernate does not issue N+1 queries but that instead the @NamedEntityGraph annotation has forced Hibernate to load the orders per left outer join. This is of course a subtle difference to the FETCH JOIN clause, where Hibernate created an inner join. The left outer join would also load customers for which no order exists in contrast to the FETCH JOIN clause, where we would only load customers that have at least one order.
Interestingly is also that Hibernate loads more than the specified attributes for the tables CustomerEntity and OrderEntity. As this conflicts with the specification of @NamedEntityGraph (section 3.7.4) I have created an JIRA issue for that.
Conclusion: We have seen that with JPA 2.1 we have two solutions for the N+1 problem: We can either use the FETCH JOIN clause to eagerly fetch a @OneToMany relation, which results in an inner join, or we can use @NamedEntityGraph feature that lets us specify which @OneToMany relation to load via left outer join.
Tracing SQL statements in JBoss AS 7 using a custom logging handler
Using an ORM to abstract from your specific database and to let it create and issue all the SQL statements you would have to write by hand yourself seems handy. This is what made ORM solutions popular.
But it also comes with a downside: As the ORM does a lot of work for you, you lose to some degree control over the generated SQL and you have to rely on the ORM to create a high-performance statement for you. But it can happen that the SQL generated by the ORM is not what you might have written by hand and expected the ORM to do for you. In this case you have to get back control over the SQL and put your hands on the code again.
In huge applications this task is not as trivial, as there might be hundreds of statements issued to the database that stem from hundreds of lines of Java code that makes heavy usage of JPA features. Tracing the SQL statement that your database profiling tool has identified as problematic down to the actual code line becomes tedious.
We know that we can enable SQL statement logging for Hibernate with the following two lines in our persistence.xml:
<property name="hibernate.show_sql" value="true"/> <property name="hibernate.format_sql" value="true"/>
But this will only output the already generated SQL; the actual Java code line is still not visible. For smaller applications it might be feasible to attach a debugger to the application server and debug through the code until you have found the line that logs the problematic SQL statement, but for bigger applications this is time consuming.
As Hibernate itself does not provide any means of intercepting the logging and enhance it with more information, we will have to do this on our own. The JBoss documentation indicates that it is possible to write your own custom logging handler. As this logging handler receives all the logging messages and therewith also the messages produces by Hibernate with enabled SQL logging, we can try to find the line we are looking for and then output a stack trace to our own log file.
Writing a custom logging handler turns out to be very simple. All you have to do is setup a small project with a class that extends the class Handler from the JDK package java.util.logging:
package mypackage;
import java.util.logging.Handler;
import java.util.logging.LogRecord;
public class MyJBossLogger extends Handler {
@Override
public void publish(LogRecord record) {
}
@Override
public void flush() {
}
@Override
public void close() throws SecurityException {
}
}
The publish() method receives all logging output in form of an instance of LogRecord. Its method getMessage() lets us access the output directly. Hence we can match this message against some keywords we have loaded from some configuration file:
@Override
public void publish(LogRecord record) {
String message = record.getMessage();
buffer.add(message + "\n");
if (keywords == null) {
keywords = loadKeywords();
}
if (matches(message, keywords)) {
String stacktrace = "\nStacktrace:\n";
StackTraceElement[] stackTrace = Thread.currentThread().getStackTrace();
for (StackTraceElement element : stackTrace) {
stacktrace += element.toString() + "\n";
}
buffer.add(stacktrace);
flush();
}
}
Buffer is here some simple data structure (e.g. guava’s EvictingQueue) that buffers the last lines, as the method publish() is called for each line(!) of output. As a complete SQL statement spans more than one line, we have to remember a couple of them. Next to the buffered lines and the current line we also output a String representation of the current stack trace. This tells us later in the log file from where we are called and therewith which line of Java code in our project causes the current statement.
Once we have compiled the project we can copy the resulting jar file to the newly created folder structure under: $JBOSS_HOME/modules/system/layers/base/com/mydomain/mymodule/main (for JBoss AS 7.2). In order to tell JBoss AS about our new module, we have to create a XML file called module.xml with the following content:
<?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.1" name="com.mydomain.mymodule"> <resources> <resource-root path="MyJBossLogger-0.0.1-SNAPSHOT.jar"/> </resources> </module>
The name of the module corresponds to the path within the JBoss modules folder. It will also be used in the configuration file to configure our custom logging handler:
... <subsystem xmlns="urn:jboss:domain:logging:1.2"> <custom-handler name="CUSTOM" module="com.mydomain.mymodule" class="com.mydomain.mymodule.MyJBossLogger"> <level name="DEBUG"/> </custom-handler> ...
When we implement the flush() method of our logging handler to write the output to some log file, we will see something like the following (of course in condensed form):
Hibernate: select ... from customer ... Stacktrace: java.lang.Thread.getStackTrace(Thread.java:1568) com.mydomain.mymodule.MyJBossLogger.publish(MyJBossLogger.java:20) org.jboss.logmanager.LoggerNode.publish(LoggerNode.java:292) org.jboss.logmanager.LoggerNode.publish(LoggerNode.java:300) org.jboss.logmanager.Logger.logRaw(Logger.java:721) org.jboss.logmanager.Logger.log(Logger.java:506) ... com.mydomain.myapp.ArticleEntity.getCustomers(ArticleRepository.java:234) ...
Here we can see clearly which OneToMany relation causes the problematic select statement we were looking for.
Conclusion: Using a custom logging handler to inject the current stack trace into the logging of the SQL statements may help you when you want to find the
exact location in the source code where a concrete query is issued. It turned also out that writing your own custom logging handler for JBoss AS is also a straight forward task.
API design and performance
When you design a new API you have to take a lot of decisions. These decisions are based on a number of design principles. Joshua Bloch has summarized some of them in his presentation “How to Design a Good API and Why it Matters”. The main principles he mentions are:
- Easy to learn
- Easy to use
- Hard to misuse
- Easy to read and maintain code that uses it
- Sufficiently powerful to satisfy requirements
- Easy to extend
- Appropriate to audience
As we see from the list above, Joshua Bloch puts his emphasis on readability and usage. A point that is completely missing from this listing is performance. But can performance impact your design decisions at all?
To answer this question let’s try to design a simple use case in form of an API and measure its performance. Then we can have a look at the results and decide whether performance considerations have an impact on the API or not. As an example we take the classic use case of loading a list of customers from some service/storage. What we also want to consider is the fact that not all users are allowed to perform this operation. Hence we will have to implement some kind of permission check. To implement this check and to return this information back to the caller, we have multiple ways to do so. The first try would look like this one:
List<Customer> loadCustomersWithException() throws PermissionDeniedException
Here we model an explicit exception for the case the caller has not the right to retrieve the list of customers. The method returns a list of Customer objects while we assume that the user can be retrieved from some container or ThreadLocal implementation and has not to be passed to each method.
The method signature above is easy to use and hard to misuse. Code that uses this method is also easy to read:
try {
List<Customer> customerList = api.loadCustomersWithException();
doSomething(customerList);
} catch (PermissionDeniedException e) {
handleException();
}
The reader immediately sees that a list of Customers is loaded and that we perform some follow-up action only in case we don’t get a PermissionDeniedException. But in terms of performance exceptions do cost some CPU time as the JVM has to stop the normal code execution and walk up the stack to find the position where the execution has to be continued. This is also extremely hard if we consider the architecture of modern processors with their eager execution of code sequences in pipelines. So would it be better in terms of performance to introduce another way of informing the caller about the missing permission?
The first idea would be to create another method in order to check the permission before calling the method that eventually throws an exception. The caller code would then look like this:
if(api.hasPermissionToLoadCustomers()) {
List<Customer> customerList = api.loadCustomers();
doSomething(customerList);
}
The code is still readable, but we have introduced another method call that also costs runtime. But now we are sure that the exception won’t be thrown; hence we can omit the try/catch block. This code now violates the principle “Easy to use”, as we now have to invoke two methods for one use case instead of one. You have to pay attention not to forget the additional call for each retrieval operation. With regard to the whole project, your code will be cluttered with hundreds of permission checks.
Another idea to overcome the exception is to provide an empty list to the API call and let the implementation fill it. The return value can then be a boolean value indicating if the user has had the permission to execute the operation or if the list is empty because no customers have been found. As this sounds like C or C++ programming where the caller manages the memory of the structures that the callees uses, this approach costs the construction of an empty list even if you don’t have a permission to retrieve the list at all:
List<Customer> customerList = new ArrayList<Customer>();
boolean hasPermission = api.loadCustomersWithListAsParameter(customerList);
if(hasPermission) {
doSomething(customerList);
}
One last approach to solve the problem to return two pieces of information to the caller would be the introduction of a new class that holds next to the returned list of Customers also a boolean flag indicating if the user has had the permission to perform this operation:
CustomerList customerList = api.loadCustomersWithReturnClass();
if(customerList.isUserHadPermission()) {
doSomething(customerList.getCustomerList());
}
Again we have to create additional objects that cost memory and performance, and we also have to deal with an additional class that has nothing more to do than to serve as a simple data holder to provide the two pieces of information. Although this approach is again easy to use and creates readable code, it creates additional overhead in order to maintain the separate class and has some kind of awkward means to indicate that an empty list is empty because of the missing permission.
After having introduced these different approaches it is now time to measure their performance, one time for the case the caller has the permission and one time for the case the caller does not have the necessary permission. The results in the following table are shown for the first case with 1.000.000 repetitions:
| Measurement | Time[ms] |
| testLoadCustomersWithExceptionWithPermission | 33 |
| testLoadCustomersWithExceptionAndCheckWithPermission | 34 |
| testLoadCustomersWithReturnClassWithPermission | 41 |
| testLoadCustomersWithListAsParameterWithPermission | 66 |
As we have expected before, the two approaches that introduce an additional class respectively pass an empty list cost more performance than the approaches that use an exception. Even the approach that uses a dedicated method call to check for the permission is not much slower than the one without it.
The following table now shows the results for the case where the caller does not have the permission to retrieve the list:
| Measurement | Time[ms] |
| testLoadCustomersWithExceptionNoPermission | 1187 |
| testLoadCustomersWithExceptionAndCheckNoPermission | 5 |
| testLoadCustomersWithReturnClassNoPermission | 4 |
| testLoadCustomersWithListAsParameterNoPermission | 5 |
Not surprisingly the approach where a dedicated exception is thrown is much slower than the other approaches. The magnitude of this impact is much higher than one would expect before. But from the table above we already know the solution for this case: Just introduce another method that can be used to check for the permission ahead, in case you expect a lot of permission denied use cases. The huge difference in runtime between the with and without permission use cases can be explained by the fact that I have returned an ArrayList with one Customer object in case the caller was in possession of the permission; hence the loadCustomer() calls where a bit more expensive than in case the user did not possess this permission.
Conclusion: When performance is a critical factor, you also have to consider it when designing a new API. As we have seen from the measurements above, this may lead to solutions that violate common principles of API design like “easy to use” and “hard to misuse”.
Injecting configuration values using CDI’s InjectionPoint
Dependency injection is a great technology for the organization of class dependencies. All class instances you need in your current class are provided at runtime from the DI container. But what about your configuration?
Of course, you can create a “Configuration” class and inject this class everywhere you need it and get the necessary value(s) from it. But CDI lets you do this even more fine-grained using the InjectionPoint concept.
If you write a @Produces method you can let your CDI container also inject some information about the current code where the newly created/produced value is inject into. A complete list of the available methods can be found here. The interesting point is, that you can query this class for all the annotations the current injection point has:
Annotated annotated = injectionPoint.getAnnotated(); ConfigurationValue annotation = annotated.getAnnotation(ConfigurationValue.class);
As the example code above shows, we can introduce a simple @Qualifier annotation that marks all the injection points where we need a specific configuration value. In this blog post we just want to use strings as configuration values, but the whole concept can of course be extended to other data types as well. The already mentioned @Qualifier annotation looks like the following one:
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface ConfigurationValue {
@Nonbinding ConfigurationKey key();
}
public enum ConfigurationKey {
DefaultDirectory, Version, BuildTimestamp, Producer
}
The annotation has of course the retention policy RUNTIME because the CDI container has to evaluate it while the application is running. It can be used for fields and methods. Beyond that we also create a key attribute, which is backed by the enum ConfigurationKey. Here we can introduce all configuration values we need. In our example this for example a configuration value for a default directory, for the version of the program and so on. We mark this attribute as @Nonbinding to prevent that the value of this attribute is used by the CDI container to choose the correct producer method. If we would not use @Nonbinding we would have to write a @Produces method for each value of the enum. But here we want to handle all this within one method.
The @Produces method for strings that are annotated with @ConfigurationKey is shown in the following code example:
@Produces
@ConfigurationValue(key=ConfigurationKey.Producer)
public String produceConfigurationValue(InjectionPoint injectionPoint) {
Annotated annotated = injectionPoint.getAnnotated();
ConfigurationValue annotation = annotated.getAnnotation(ConfigurationValue.class);
if (annotation != null) {
ConfigurationKey key = annotation.key();
if (key != null) {
switch (key) {
case DefaultDirectory:
return System.getProperty("user.dir");
case Version:
return JB5n.createInstance(Configuration.class).version();
case BuildTimestamp:
return JB5n.createInstance(Configuration.class).timestamp();
}
}
}
throw new IllegalStateException("No key for injection point: " + injectionPoint);
}
The @Produces method gets the InjectionPoint injected as a parameter, so that we can inspect its values. As we are interested in the annotations of the injection point, we have a look if the current injection point is annotated with @ConfigurationValue. If this is the case, we have a look at the @ConfigurationValue’s key attribute and decide which value we return. That’s it. In a more complex application we can of course load the configuration from some files or some other kind of data store. But the concept remains the same.
Now we can easily let the CDI container inject the configuration values we need simply with these two lines of code:
@Inject @ConfigurationValue(key = ConfigurationKey.DefaultDirectory)
private String defaultDirectory;
Conclusion: Making a set of configuration values accessible throughout the whole application has never been easier.
Securing a JSF application with Java EE security and JBoss AS 7.x
A common requirement for enterprise applications is to have all JSF pages protected behind a login page. Sometimes you even want to have protected areas inside the application that are only accessible by users that own a specific role. The Java EE standards come with all the means you need to implement a web application that is protected by some security constraints. In this blog post we want to develop a simple application that demonstrates the usage of these means and shows how you can build a complete JSF application for two different roles. As the solution might look straight forward at first glance, there are a few pitfalls one has to pay attention to.
The first point we have to care about, is the folder layout of our application. We have three different kinds of pages:
- The login page and the error page for the login should be accessible by all users.
- We have a home page that should only be accessible for authenticated users.
- We have a protected page that should only be visible for users of the role protected-role.
These three types of pages are therefore put into three different folders: the root folder src/main/webapp, the folder src/main/webapp/pages and the protected page resides in src/main/webapp/pages/protected:
The web.xml file is the place to define which roles we want to use and how to map the accessibility of some URL pattern to these roles:
<security-constraint>
<web-resource-collection>
<web-resource-name>pages</web-resource-name>
<url-pattern>/pages/*</url-pattern>
<http-method>PUT</http-method>
<http-method>DELETE</http-method>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>security-role</role-name>
<role-name>protected-role</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>protected</web-resource-name>
<url-pattern>/pages/protected/*</url-pattern>
<http-method>PUT</http-method>
<http-method>DELETE</http-method>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>protected-role</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<role-name>security-role</role-name>
</security-role>
<security-role>
<role-name>protected-role</role-name>
</security-role>
As you can see we define two roles: security-role and protected-role. URLs matching the pattern /pages/* are only accessible by users that own the roles security-role and protected-role, whereas the pages under /pages/protected/* are restricted to users with the role protected-role.
Another point you may stumble upon is the welcome page. At first guess you would want to the specify the login page as welcome page. But this does not work, as the login module of the servlet container automatically redirects all unauthorized accesses to the login page. Therefore we specify the home page of our application as welcome page. This is already a protected page, but the user will get redirected to the login page automatically when he calls its URL directly.
<welcome-file-list>
<welcome-file>pages/home.xhtml</welcome-file>
</welcome-file-list>
Now we are nearly done with the web.xml page. All we to do is to define the authentication method as well as the login page and the error page, which is shown in case the user enters invalid credentials. One has to page attention that both pages don’t include protected URLs (e.g. CSS or JavaScript files), otherwise even the access to these two pages is forbidden and the user gets an Application Server specific error page to see.
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/login.xhtml</form-login-page>
<form-error-page>/error.xhtml</form-error-page>
</form-login-config>
</login-config>
As we are going to deploy the application to the JBoss Application Server, we provide a file named jboss-web.xml that connects our application to a security-domain:
<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
<security-domain>java:/jaas/other</security-domain>
</jboss-web>
The “other” security-domain is configured inside the standalone.xml. The default configuration requires that the user passes the “RealmUsersRoles” login module, which gets its user and role definitions from the two files application-users.properties and application-roles.properties inside the configuration folder. You can use the provided add-user script to add a new user to this realm:
What type of user do you wish to add? a) Management User (mgmt-users.properties) b) Application User (application-users.properties) (a): b Enter the details of the new user to add. Realm (ApplicationRealm) : Username : bart Password : Re-enter Password : What roles do you want this user to belong to? (Please enter a comma separated list, or leave blank for none) : security-role,protected-role About to add user 'bart' for realm 'ApplicationRealm' Is this correct yes/no? yes
Here it is important to choose the correct realm (ApplicationRealm), as this realm is configured by default in the standalone.xml for the “other” login module. This is also the place where you provide the roles the user possesses as a comma separated list.
<form method="POST" action="j_security_check" id=""> <h:panelGrid id="panel" columns="2" border="1" cellpadding="4" cellspacing="4"> <h:outputLabel for="j_username" value="Username:" /> <input type="text" name="j_username"/> <h:outputLabel for="j_password" value="Password:" /> <input type="password" name="j_password"/> <h:panelGroup> <input type="submit" value="Login"/> </h:panelGroup> </h:panelGrid> </form>
The next step is to implement a simple login form that submits its data to the login module. Note the ids of the input fields as well as the action of the form. This way the form is posted to the login module, which extracts the entered username and password from the request. JSF developers may wonder why we use a standard HTML form instead of the element. The reason for this is that the JSF form elements spans its own namespace and therefore the ids of the input fields are prefixed with the id of the form (and this form id cannot be empty).
If the user has passed the login form, we present him a home page. But the link to the protected page should only be accessible for users that own the role protected-role. This can be accomplished by the following rendered condition:
<h:link value="Protected page" outcome="protected/protected" rendered="#{facesContext.externalContext.isUserInRole('protected-role')}"/>
Last but not least we need the logout functionality. For this case we implement a simple backing bean like the following one that invalidates the user’s session and redirects him back to the login page:
@Named(value = "login")
public class Login {
public String logout() {
FacesContext.getCurrentInstance().getExternalContext().invalidateSession();
return "/login";
}
}
As usual the complete source code can be found on github.
Building and testing a websocket server with undertow
The upcoming version of JBoss Application Server will no longer use Tomcat as integrated webserver, but will replace it with undertow. The architecture of undertow is based on handlers that can be added dynamically via a Builder API to the server. This approach is similar to the way of constructing a webserver in Node.js. It allows developers to embed the undertow webserver easily into their applications. As the addition of features is done via the Builder API, one can only add the features that are really required in one’s application. Beyond that undertow supports WebSockets and the Servlet API in version 3.1. It can be run as blocking or non-blocking server and it is said, that first tests have proven that undertow is the fastest webserver written in Java.
As all of this sounds very promising, so let’s try to set up a simple websocket server. As usual we start by creating a simple java project and add the undertow maven dependency:
<dependency> <groupId>io.undertow</groupId> <artifactId>undertow-core</artifactId> <version>1.0.0.Beta20</version> </dependency>
With undertow’s Builder API our buildAndStartServer() method looks like this:
public void buildAndStartServer(int port, String host) {
server = Undertow.builder()
.addListener(port, host)
.setHandler(getWebSocketHandler())
.build();
server.start();
}
We just add a listener that specifies the port and host to listen for incoming connections and afterwards add a websocket handler. As the websocket handler code is a little bit more comprehensive, I have put it into its own method:
private PathHandler getWebSocketHandler() {
return path().addPath("/websocket", websocket(new WebSocketConnectionCallback() {
@Override
public void onConnect(WebSocketHttpExchange exchange, WebSocketChannel channel) {
channel.getReceiveSetter().set(new AbstractReceiveListener() {
@Override
protected void onFullTextMessage(WebSocketChannel channel, BufferedTextMessage message) {
String data = message.getData();
lastReceivedMessage = data;
LOGGER.info("Received data: "+data);
WebSockets.sendText(data, channel, null);
}
});
channel.resumeReceives();
}
}))
.addPath("/", resource(new ClassPathResourceManager(WebSocketServer.class.getClassLoader(), WebSocketServer.class.getPackage()))
.addWelcomeFiles("index.html"));
}
Let’s go line by line through this code snippet. First of all we add a new path: /websocket. The second argument of the addPath() methods lets us specify what kind of protocol we want to use for this path. In our case we create a new WebSocket. The anonymous implementation has a onConnect() method in which we set an implementation of AbstractReceiveListener. Here we have a convenient method onFullTextMessage() that is called when a client has sent us a text message. A call of getData() fetches the actual message we have received. In this simple example we just echo this string back to client to validate that the roundtrip from the client to server and back works.
To perform some simple manual tests we also add a second resource under the path / which serves some static HTML and JavaScript files. The directory that contains these files is given as an instance of ClassPathResourceManager. The call of addWelcomeFiles() tells undertow which file to server when the client asks for the path /.
The index.html looks like this:
</pre>
<html>
<head><title>Web Socket Test</title></head>
<body>
<script src="jquery-2.0.3.min.js"></script>
<script src="jquery.gracefulWebSocket.js"></script>
<script src="websocket.js"></script>
<form onsubmit="return false;">
<input type="text" name="message" value="Hello, World!"/>
<input type="button" value="Send Web Socket Data" onclick="send(this.form.message.value)"/>
</form>
<div id="output"></div>
</body>
</html>
<pre>
Our JavaScript code is swapped out to the websocket.js file. We use jquery and the jquery-Plugin gracefulWebSocket to ease the client side development:
var ws = $.gracefulWebSocket("ws://127.0.0.1:8080/websocket");
ws.onmessage = function(event) {
var messageFromServer = event.data;
$('#output').append('Received: '+messageFromServer+'');
}
function send(message) {
ws.send(message);
}
After having created a WebSocket object by calling $.gracefulWebSocket() we can register a callback function for incoming messages. In this method we only append the message string to the DOM of the page. The send() method is just a call to gracefulWebSocket’s send() method.
When we now start our application and open the URL http://127.0.0.1:8080/ in our webbrowser we see the following page:
Entering some string and hitting the “Send Web Socket Data” button sends the message to the server, which in response echos it back to the client.
Now that we know that everything works as expected, we want to protect our code against regression with a junit test case. As a websocket client I have chosen the library jetty-websocket:
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-websocket</artifactId>
<version>8.1.0.RC5</version>
<scope>test</scope>
</dependency>
In the test case we build and start the websocket server to open a new connection to the websocket port. The WebSocket implementation of jetty-websocket allows us to implement two callback methods for the open and close events. Within the open callback we send the test message to the client. The rest of the code waits for the connection to be established, closes it and asserts that the server has received the message:
@Test
public void testStartAndBuild() throws Exception {
subject = new WebSocketServer();
subject.buildAndStartServer(8080, "127.0.0.1");
WebSocketClient client = new WebSocketClient();
Future connectionFuture = client.open(new URI("ws://localhost:8080/websocket"), new WebSocket() {
@Override
public void onOpen(Connection connection) {
LOGGER.info("onOpen");
try {
connection.sendMessage("TestMessage");
} catch (IOException e) {
LOGGER.error("Failed to send message: "+e.getMessage(), e);
}
}
@Override
public void onClose(int i, String s) {
LOGGER.info("onClose");
}
});
WebSocket.Connection connection = connectionFuture.get(2, TimeUnit.SECONDS);
assertThat(connection, is(notNullValue()));
connection.close();
subject.stopServer();
Thread.sleep(1000);
assertThat(subject.lastReceivedMessage, is("TestMessage"));
}
As usual you can find the source code on github.
Conclusion: Undertow’s Builder API makes it easy to construct a websocket server and in general an embedded webserver that fits your needs. This also eases automatic testing as you do not need any specific maven plugin that starts and stops your server before and after your integration tests. Beyond that the jquery plugin jquery-graceful-websocket lets you send and receive messages over websockets with only a few lines of code.
Analyze package dependencies with structure101
One key to a stable application is a well-structured codebase. We know that we should build as many black boxes as possible, because as soon as one black box is finished, we no longer have to think about its interior. You just use the code you or another team member has written through a well-defined interface. This gives you the possibility to concentrate on the next feature you want to add.
When we think about black boxes we often have classes or whole jar packages in mind. Classes should of course be black boxes, no discussion about that. The same is true for jar packages. But in-between classes and jar packages there is another level of structure, which is often not seen this directly as a black box: packages.
Packages are often second class citizens and their interrelationship is not analyzed this thoroughly. But there is a great tool for such analysis: Structure101. It in general helps you to monitor and verify the dependency structures and complexity of your project by the means of well-organized diagrams.
So let’s start with a sample project. I have taken one of my own projects for this: japicmp is a tool to compute the differences between the API of two jar archives in means of what methods and classes have changed. structure101 has a great composition view, which shows you the dependencies between the packages of a project. This is how it looks for the current version of japicmp:
Cleary we can see for example that the cli package, which is responsible for the command-line parsing, uses the exception as well as the config package and is used itself by the main package, where the main() method resides. With the cli package everything seems to be OK. But what about the three packages cmp, util and model. The difference computation between the classes and methods, i.e. the business logic, resides in the package cmp. Hence it should use the model as well as the util package. But these two packages should not have any backward dependencies. This problem is also shown in the matrix view:
When we take a closer look at the tangle between these three packages, we see that the class AccessModifier, which is located in the cmp package, is used from the util package:
Beyond that, this class is also used in the model. This clearly indicates that the class should rather stay in the model package as in the cmp package. This seems to make sense, as the access modifiers of a class or method are part of the model of a jar archive and do not belong into the business logic. If we move this class to the model package, we get the following result:
This looks much better. We do not have any tangles within the package structure. The nice layout also shows clearly that the whole application depends on the model, as the package is located at the bottom of the diagram. The business logic, which resides within cmp, is called from the main package and uses util, config and the model, as it should be. The same is true for the output package, where the implementations for the cli and xml output reside. This package uses the config as well as the model, once it is computed.
Conclusion: Packages should not be second class citizens but help you to structure your application such that it is easy to overview the code and separate functionality. Tools like structure101 help you to analyze the dependencies between packages and therefore let packages be an important level between the jar on the one side and the class on the other side.
Testing HTML5 canvas applications with sikuli and arquillian
HTML5 introduces a great new element that can be used to draw arbitrary content on a pane: the canvas element. What has been a standard feature for fat client applications for decades is now introduced to the world of web applications. Web developers no longer need to use proprietary plugins to draw images or charts in their applications.
But when it comes for testing, this new feature imposes new challenges to the web development community. How to test that the canvas element is in an appropriate state at some point in time? Standard technologies like selenium focus on the markup that is generated by the web server and not on the pixels drawn on the canvas.
More promising in this field are technologies that use image processing to verify that an application renders its data correctly. One of these frameworks is sikuli. Sikuli is an open-source research project that was started at the MIT and is now maintained by Raimund Hocke.
To give a more practical introduction, let’s assume we have a simple web application that uses the HTML5 canvas element to implement some simple image processing functionality like a grayscale, a brighten and a threshold filter as well as an undo button (the code for this application can be found as usual on github):
The installation of sikuli is (of course) platform dependent. The installer, which can be downloaded from the sikuli download page, is a Java Swing application that asks you about your typical usage pattern. As we do not want to use the python IDE, we choose option 4 from the list of options. The actual jar file is then downloaded and prepared for our OS. After the installation process has finished, we find an OS dependent jar file within the installation directory. As our example project uses maven as build system, we have to introduce a system scope dependency after we have copied the library into the lib folder:
<dependency>
<groupId>org.sikuli</groupId>
<artifactId>sikuli</artifactId>
<version>1.0</version>
<scope>system</scope>
<systemPath>${basedir}/lib/sikuli-java.jar</systemPath>
</dependency>
When sikuli is used for the first time, it extracts some native libraries into a new folder, here in our example into ${basedir}/lib/libs. This folder has to be added to the user’s path environment variable.
Now that we have installed sikuli, let’s setup arquillian so that we can write our first unit test. How to setup arquillian is described for example here. As I don’t want to repeat everything, in the following you will find only the unit test class:
@RunWith(Arquillian.class)
public class FilterTest {
public static final String WEBAPP_SRC = "src/main/webapp";
@ArquillianResource
URL deploymentURL;
private Screen screen;
@Before
public void before() throws URISyntaxException, IOException {
screen = new Screen();
if (Desktop.isDesktopSupported()) {
Desktop.getDesktop().browse(deploymentURL.toURI());
} else {
fail();
}
}
@Deployment
public static WebArchive createDeployment() {
return ShrinkWrap.create(WebArchive.class, "html5-sikuli-webapp.war")
.addClasses(HomeBackingBean.class)
.addAsWebResource(new File(WEBAPP_SRC, "home.xhtml"))
.addAsWebResource(new File(WEBAPP_SRC, "resources/css/style.css"), "resources/css/style.css")
.addAsWebResource(new File(WEBAPP_SRC, "resources/images/rom.jpg"), "resources/images/rom.jpg")
.addAsWebResource(new File(WEBAPP_SRC, "resources/js/html5Sikuli.js"), "resources/js/html5Sikuli.js")
.addAsWebResource(new File(WEBAPP_SRC, "resources/js/jquery-2.0.3.js"), "resources/js/jquery-2.0.3.js")
.addAsWebInfResource(EmptyAsset.INSTANCE, "beans.xml")
.setWebXML(new File(WEBAPP_SRC, "WEB-INF/web.xml"));
}
The createDeployment() method sets up the war archive, which is deployed by arquillian to JBoss AS 7.1.1.Final (see arquillian.xml file). In our @Before method we use the SDK class Desktop to open the default browser and point it to the deployment URL. Here we also create an instance of sikuli’s class Screen. This class provides all methods needed to perform the interaction with our application. Let’s look at this in more detail:
@Test
@RunAsClient
public void testGrayScale() throws FindFailed {
screen.wait(getFullPath("originalImage.png"));
screen.find(getFullPath("btnUndo_disabled.png"));
screen.click(getFullPath("btnGrayscale.png"));
screen.find(getPattern("grayscaleImage.png", 0.9f));
screen.click(getFullPath("btnUndo_enabled.png"));
screen.click(getPattern("originalImage.png", 0.9f));
}
private Pattern getPattern(String path, float similarity) {
Pattern p = new Pattern(getFullPath(path));
return p.similar(similarity);
}
private String getFullPath(String path) {
return "src/test/resources/img/" + path;
}
As sikuli is based on image processing, we can define where to click and what to verify with screenshots we have taken before. In this simple example I have stored all screenshots as png files within the src/test/resources/img folder of our project. More advanced projects may need a more sophisticated folder hierarchy. As you can see, we first wait for the application to show up. Once sikuli has found the first screenshot, we verify that the button “Undo” is disabled. This is done by calling the method find() with an image of the disabled button. Now we can click on the button “Grayscale” (again specified by an image of the button) and then verify that the grayscale version of the image is found on the screen.
Sikuli does not only compare both images pixel by pixel, but if you like it computes the similarity of the found screen region with the requested region. This helps when you need to be more tolerant (e.g. if you want to test the application in different browsers and these render the buttons slightly different). The default value for the similarity attribute is 0.7f, but if you increase it to 1.0f you have a simple pixel by pixel comparison.
But this is not all. With sikuli you can do nearly all things you could do as human interactor:
- Type characters using screen.type()
- Double click with screen.doubleClick()
- Perform drag and drop operations with screen.dragDrop()
- Use the mouse wheel
- …
Conclusion: Sikuli is a powerful and easy to use tool to perform integration tests for web applications that heavily rely on HTML5’s canvas object. The same is of course true for standard fat client applications (Swing, JavaFX). Together with arquillian you can setup comprehensive test suites that cover a lot of “real” use cases.
Martin's Developer World 