The Kitchen in the Zoo - java tag

100% code coverage, Hibernate Validator and Design by Contract

Mon, 28 Nov 2011 07:29:37 GMT

Code coverage in unit testing was one of the first things I learned in my software engineering career. The company I worked at taught me that you should have 100% coverage as a goal, but achieving it does not mean there are no bugs in the system. At that time, I worked at a company whose big thing was that they delivered very reliable billing software to telecomms operators. We used to invest as much time writing unit tests as we did writing the code. If you included unit tests, integration tests, system tests and acceptance tests, more time was spent testing than designing and implementing the code which ran in production. It was impressive and I have never worked with or for a company with that kind of model since, although I am sure there are many companies which operate like that.

The other day I was thinking back to those days and reading up about unit testing to refresh myself in preparation for a unit testing course I'm attending soon (don't want the instructor to know more than me!) and I started to wonder about what kind of code could be fully covered during unit testing, but which could still contain a bug. While I learned that 100% coverage should be the goal, in over 10 years I have never worked on a project which achieved that. So I have never surprised to find a bug in code which I thought was "fully" tested.

It's fun write whacky code - you don't normally try and write bugs :-) I started with the specification:

    /**      * @return String "a" or "b" depending upon the values      * passed to the init method. If variable "a" is true,      * then string "a" is returned. If variable "b" is true,      * then "b" is returned. If neither is true, then "" is      * returned. Variable "b" is important than "a", so if      * both are true then return "b".      */
Now, the tricky part was to write code which contained a bug yet was easy to cover with incomplete tests. I came up with the following. The specification above is for the "getResult()" method.

public class SomeClass {     private boolean a;     private boolean b;     public SomeClass init(boolean a, boolean b) {         this.a = a;         this.b = b;         return this;     }     public String getResult() {         String s = "";         if(a) {             s = "a";         }         if(b){             s += "b"; // <-- oops!         }         return s;     } }
The "bug" is in the method "getResult" and the problem is that instead of just an assignment, the "plus equals" operator has been used. An "else" would probably make the code a little safer too. But I think code like this is quite typical of the buggy code that finds its way into productive systems. Even the best programmers have lapses of concentration where they write typos like this (especially in open plan offices!).

The unit test which a programmer trying to achieve 100% coverage, would look something like this:

    @Test     public void test() {         assertEquals("a", new SomeClass().init(true, false).getResult());         assertEquals("b", new SomeClass().init(false, true).getResult());     }
Using Emma for Eclipse I measured complete coverage. But wait! There is still a bug. The code does not do what it says in the Javadoc spec. If I initialise the object with "true, true", then the result will be "ab", because of the "plus equals" operator. So even though I have 100% coverage, I still have a bug.

I asked myself what that means to me as a programmer. What do I need to look out for, when writing tests. Imagine the code above was tucked away among hundereds of other lines of code, then the chances of seeing it are really quite small. The test wouldn't be just two lines long and the problem wouldn't be jumping out of the page.

One way to look at the problem is to say that there is a bug because the code isn't fulfilling its contract. OK, I use "contract" in the loose sense of the word, but the Javadoc is basically a contract. It tells anyone calling that method what to expect, yet the codes is not doing what the user expects.

So perhaps one solution is to not only entirely exercise the code, but entirely exercise the contract? Is there a way to translate the Javadoc contract into something more concrete which the testing tools can help me check? Yes, namely my using some kind of Design (or Program) by Contract (DBC or PBC) framework. JSR-303 isn't strictly DBC, but close. It lets you use annotations to state your expectations about parameters passed to methods, as well as your expectation about the result being returned. You can create your own complex constraints quite easily. I added the following annotations to my code to help in my quest for bug free code:

    @Valid     @NotNull     @Size(min=0, max=1)     public String getResult() {         ...
Now, method validation (validating method calls, rather than validating the bean itself) is something which comes as an extra in Hibernate Validator, and which really isn't part of JSR-303 - it's only described in Appendix C as optional. To test this, I used Google Guice to add an AOP interceptor to any methods marked with the @Valid annotation, and in that interceptor, I call the Hibernate Method Validator. I end up with something like this:

. . .     Injector injector = Guice.createInjector(new AbstractModule(){         protected void configure() {             bindInterceptor(Matchers.any(),                     Matchers.annotatedWith(Valid.class),                     new MethodValidatorInterceptor());         }     });     SomeClass someClass = injector.getInstance(SomeClass.class);     someClass.init(true, false);     assertEquals("a", someClass.getResult());     someClass = injector.getInstance(SomeClass.class);     someClass.init(false, true);     assertEquals("b", someClass.getResult()); . . . public class MethodValidatorInterceptor<T> implements MethodInterceptor {     public Object invoke(MethodInvocation invocation) throws Throwable {         //validate all inputs         Set<MethodConstraintViolation<T>> mcvs =             methodValidator.validateAllParameters((T)invocation.getThis(),                invocation.getMethod(), invocation.getArguments());         if(mcvs.size() != 0){             throw new IllegalArgumentException(String.valueOf(mcvs));         }         //call through to the actual method being called         Object ret = invocation.proceed();         //validate result         mcvs = methodValidator.validateReturnValue((T)invocation.getThis(),             invocation.getMethod(), ret);         if(mcvs.size() != 0){             throw new IllegalArgumentException(String.valueOf(mcvs));         }         return ret;     } } . . .
The above is something which a (Java EE) container should do for me - I was just messing around with simple classes in a simple Java Project. Now, it isn't quite complete, because I still have 100% coverage, and I still have that bug, because the new annotations haven't really done anything useful. Well that isn't entirely true - the reader of the code knows that the contract is a little stricter than it was when it was simple Javadoc. The reader may assume that the system will check these constraints when the method is called. But while there is still a bug, I've laid the path for adding some full pre- or post-conditions. The next step was to add a new annotation, an interface and make use of them in the interceptor.

@Target( { ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface PreCondition {     Class<? extends ConditionChecker> implementation(); } /** Any pre- or post-condition is written in   * an implementation of this interface   */ public interface ConditionChecker {     void checkCondition()         throws ConstraintViolationException; }
The annotation can be added to the business code, in this case to add a pre-condition. I created a similar annotation for post-conditions. When I add the pre-condition to a method, I also state which class contains the code for checking that pre-condition:

    @Valid     @NotNull     @Size(min=0, max=1)     @PreCondition(implementation=MyPreAndPostCondition.class)     public String getResult() {         ...
The interceptor can check for the presence of such a pre-condition annotation before calling through to the method being called. If the annotation is found, the interceptor attempts to create an instance of the implementation class, and calls it's "checkCondition" method.

So the final part of this puzzle is to write a pre-condition which will help me to fail to get 100% coverage when I test with the test shown near the top of this post. Here it is, implemented as a static final inner class inside the SomeClass class, so that it has access to the fields "a" and "b":

public class MyPreAndPostCondition implements ConditionChecker {     @Override     public void checkCondition()             throws ConstraintViolationException {         //im going to list all combinations of         //a and b which I support         if(!a && b) return;         if(!b && a) return;         if(!b && !a) return;         if(a && b) return;     } }
When I now test my code, I no longer get 100% coverage, because the last two lines in the pre-condition are not covered. Hooray! The tools can now tell me what I still need to test...

Now, while this technical solution works, I think it is really ugly. Like I said, if the code which is causing the problem were to be found within one or two hundred other lines of code, and were reliant on local variables rather than fields in my class, I would have no chance of using a pre-condition like this to help me locate the problem.

So to sum up, DBC isn't going to help me solve the problem that 100% code coverage can still contain errors. I think DBC frameworks (and there are a lot out there, some which do exactly what I have done here using the @PreCondition annotation) help to make contracts more concrete. If you use method validation from Hibernate Validator, you don't have to write as much Javadoc, because the reader knows that the container will give up before calling the method if anything fails to validate. To me as a programmer, that is much more satisfying than praying that some Javadoc reflects what I have really implemented.

I have known programmers who don't write tests because a DBC framework is in place and that makes them feel safe. But just because you declare a contract, does not mean the code actually works. Whether the code fails hard with a validation exception or at some time later because your code is buggy, makes no difference - both are inacceptable! From that perspective, DBC contracts are simply hints to the tester what could be useful tests, and they ensure that the code fails hard, early.

While I was refreshing my testing skills, I also learned the difference between mocks and stubs. For years I had always thought they were the same thing, but it turns out that stubs return pre-fed answers, whereby mocks check the sequence of calls to them too. On a different thread at DZone, someone made a point that unit testing was pointless because it never helped them find bugs, and it caused lots of work when refactoring, because all that does is break their tests. I'd say that this is simply a question of black box versus white box testing. Black box unit testing should never break if you refactor your code - the tests are simply clients to the code which you are refactoring, and tools like Eclipse will modify the calling code if you modify the interfaces being called, including tests. You can get pretty good testing results by just using black box tests - the large majority of the tests I write are black box tests and when I write such tests, I tend to have bug free code.

I've talked about writing contracts to help the reader determine what they should expect when they use your code. Unit tests themselves work similarly, because they show the reader examples of how to call your code and what to expect when your code changes system state. They hint to the reader how the writer intended the code to be used. While I don't advocate TDD (perhaps only because I have never been on a project which used it or at a company which valued quality enough to warrant TDD), I do encourage writing tests and using validation and pre-/post-conditions because they help document the code with the added bonus of finding the occassional bug. At the same time, I am an architect and we need to keep things like budgets in mind. You have an influence on your budget when you estimate, assuming you are allowed to do that. Your customer might push you to reduce your estimates, and that is an indication about their commitment to quality, because they won't budge on scope or delivery dates! So write as many tests as you can, within your budget and start with the code which is most complex and which gets called most often. and remember, 100% coverage is not really your best friend because bugs may still lurk.

© 2011, Ant Kutschera

Social Bookmarks :

A really simple but powerful rule engine

Sat, 12 Nov 2011 20:26:00 GMT

I have the requirement to use a rule engine. I want something light weight and fairly simple, yet powerful. While there are products out there which are super good, I don't want something with the big learning overhead. And, I fancied writing my own!

Here are my few basic requirements:

Use some kind of expression language to write the rules,
It should be possible to store rules in a database,
Rules need a priority, so that only the best can be fired,
It should also be possible to fire all matching rules,
Rules should evaluate against one input which can be an object like a tree, containing all the information which rules need to evaluate against
Predefined actions which are programmed in the system should be executed when certains rules fire.

So to help clarify those requirements, imagine the following examples:

1) In some forum system, the administrator needs to be able to configure when emails are sent.

Here, I would write some rules like "when the config flag called sendUserEmail is set to true, send an email to the user" and "when the config flag called sendAdministratorEmail is true and the user has posted less than 5 postings, send an email to the administrator".

2) A tarif system needs to be configurable, so that the best tarif can be offered to customers.

For that, I could write rules like these: "when the person is younger than 26 the Youth tarif is applicable", "when the person is older than 59, the Senior tarif is applicable", and "when the person is neither a youth, nor a senior, then they should be given the Default tarif, unless they have had an account for more than 24 months, in which case they should be offered the Loyalty tarif".

3) A train ticket can be considered to be a product. Depending upon the travel request, different products are suitable.

A rule here, could be something like: "if the travel distance is more than 100km and first class is desired, then product A is to be sold."

Finally, a more complex example, involving some iteration of the input, rather than just property evaluation:

4) Timetable software needs to deterimine when students can leave school.

A rule for that might read: "If a class contains any student under age 10, the entire class gets to leave early. Otherwise, they leave at the normal time."

So, with those requirements in mind, I went to look for an expression language. I started with the unified expression language specified in JSP 2.1. Using the jasper jar used in Tomcat and Apache Commons EL jar, I got something up and running very quickly. Then I discovered the MVEL library from Codehaus.org, which incidentally is used in Drools (the leading Java rule engine?) and it worked even better. It offers far more functionality as far as I can tell.

So, I designed my rule engine to work like this:

1) An engine is configured with some rules.

2) A rule has these attributes:
    - namespace: an engine may contain many rules, but only some may be relevant to a particular call and this namespace can be used for filtering
    - name: a unique name within a namespace
    - expression: an MVEL expression for the rule
    - outcome: a string which the engine might use if this rules expression evaluates to true
    - priority: an integer. The bigger the value, the higher the priority.
    - description: a useful description to aid the management of rules.

3) The engine is given an input object and evaluates all rules (optionally within a namespace) and either:
    a) returns all rules which evaluate to true,
    b) returns the outcome (string) from the rule with the highest priority, out of all rules evaluating to true,
    c) execute an action (defined within the application) which is associated with the outcome of the rule with the highest priority, out of all rules evaluating to true.

4) "Action"s are instances of classes which the application programmer can supply. An action is given a name. When the engine is asked to execute an action based on the rules, the name of the action matching the "winning" rule's outcome is executed.

5) A rule can be built up of "sub-rules". A subrule is only ever used as a building block on which to base more complex rules. When evaluating rules, the engine will never select a subrule to be the best (highest priority) "winning" rule, i.e. one evaluating to true. Subrules make it easier to build complex rules, as I shall show shortly.

So, time for some code!

First, let's look at the code for the tarif system:

Rule r1 = new Rule("YouthTarif", "input.person.age < 26", "YT2011", 3, "ch.maxant.someapp.tarifs", null);
Rule r2 = new Rule("SeniorTarif", "input.person.age > 59", "ST2011", 3, "ch.maxant.someapp.tarifs", null);
Rule r3 = new Rule("DefaultTarif", "!#YouthTarif && !#SeniorTarif", "DT2011", 3, "ch.maxant.someapp.tarifs", null);
Rule r4 = new Rule("LoyaltyTarif", "#DefaultTarif && input.account.ageInMonths > 24", "LT2011", 4, "ch.maxant.someapp.tarifs", null);
List<Rule> rules = Arrays.asList(r1, r2, r3, r4);

Engine engine = new Engine(rules, true);

TarifRequest request = new TarifRequest();
request.setPerson(new Person("p"));
request.setAccount(new Account());

request.getPerson().setAge(24);
request.getAccount().setAgeInMonths(5);
String tarif = engine.getBestOutcome(request);

So, in the above code, I have added 4 rules to the engine, and told the engine to throw an exception if any rule cannot be pre-compiled. Then, I created a TarifRequest, which is the input object. That object is passed into the engine, when I ask the engine to give me the best outcome. In this case, the best outcome is the string "YT2011", the name of the most suitable tarif for the customer I added to the tarif request.

How does it all work? When the engine is given the rules, it does some validation on them, and pre-compiles the rules (to improve overall performance). Notice how the first two rules refer to an object called "input"? That is the object passed into the "getBestOutcome" method on the engine. The engine passes the input object to the MVEL class together with each rules expression. Anytime an expression evaluates to "true", the rule is put to the side as a candidate to be the winner. At the end, the candidates are sorted in order of priority, and the outcome field of the rule with the highest priority is returned by the engine.

Notice how the third and fourth rules contain the '#' character. That is not standard MVEL expression language. The engine examines all rules when they are passed to it, and it replaces any token starting with a hash symbol, with the expression found in the rule named the same as the token. It wraps the expression in brackets. The logger outputs the full rule after reference rules have been resolved and replaced, just in case you want to check the rule.

In the above business case, we were only interested in the best tarif for the customer. Equally, we might have been interested in a list of possible tarifs, so that we could offer the customer a choice. In that case, we could have called the "getMatchingRules" method on the engine, which would have returned all rules, sorted by priority. The tarif names are (in this case) the "outcome" field of the rules.

In the above example, I wanted to receive any of the four outcomes, from the four rules. Sometimes however, you might want to build complex rules based on building blocks, but you might never want those building blocks to be a winning outcome. The train trip example from above can be used to show what I mean here:

Rule rule1 = new SubRule("longdistance", "input.distance > 100", "ch.maxant.produkte", null);
Rule rule2 = new SubRule("firstclass", "input.map[\"travelClass\"] == 1", "ch.maxant.produkte", null);
Rule rule3 = new Rule("productA", "#longdistance && #firstclass", "productA", 3, "ch.maxant.produkte", null);
List<Rule> rules = Arrays.asList(rule1, rule2, rule3);

Engine e = new Engine(rules, true);

TravelRequest request = new TravelRequest(150);
request.put("travelClass", 1);
List rs = e.getMatchingRules(request);

In the above code, I build rule3 from two subrules. But I never want the outcomes of those building blocks to be output from the engine. So I create them as SubRules. SubRules don't have an outcome field or priority. They are simply used to build up more complex rules. After the engine has used the sub-rules to replace all tokens beginning in a hash during initialisation, it discards the SubRules - they are not evaluated.

The TravelRequest above takes a distance in the constructor, and contains a map of additional parameters. MVEL let's you easily access map values using the syntax shown in rule 2.

Next, consider the business case of wanting to configure an forum system. The code below introduces actions. Actions are created by the application programmer and supplied to the engine. The engine takes the outcomes (as described in the first example), and searches for actions with the same names as those outcomes, and calls the "execute" method on those actions (they all implement the IAction interface). This functionality is useful when a system must be capable of predefined things, but the choice of what to do needs to be highly configurable and independent of deployment.

Rule r1 = new Rule("SendEmailToUser", "input.config.sendUserEmail == true", "SendEmailToUser", 1, "ch.maxant.someapp.config", null);
Rule r2 = new Rule("SendEmailToModerator", "input.config.sendAdministratorEmail == true and input.user.numberOfPostings < 5", "SendEmailToModerator", 2, "ch.maxant.someapp.config", null);
List<Rule> rules = Arrays.asList(r1, r2);
		
final List<String> log = new ArrayList<String>();
		
Action<ForumSetup, Void> a1 = new Action<ForumSetup, Void>("SendEmailToUser") {
  @Override
  public Void execute(ForumSetup input) {
    log.add("Sending email to user!");
    return null;
  }
};
Action<ForumSetup, Void> a2 = new Action<ForumSetup, Void>("SendEmailToModerator") {
  @Override
  public Void execute(ForumSetup input) {
    log.add("Sending email to moderator!");
    return null;
  }
};

Engine engine = new Engine(rules, true);

ForumSetup setup = new ForumSetup();
setup.getConfig().setSendUserEmail(true);
setup.getConfig().setSendAdministratorEmail(true);
setup.getUser().setNumberOfPostings(2);
			
engine.executeAllActions(setup, Arrays.asList(a1, a2));

In the code above, the actions are passed to the engine when we call the "executeAllActions" method. In this case, both actions are executed, because the setup object causes both rules to evaluate to true. Note that the actions are executed in the order of highest priority rule first. Each action is only ever executed once - it's name is noted after execution and it will not be executed again, until the engines "execute*Action*" method is called again. Also, if you only want the action associated with the best outcome to be executed, call the "executeBestAction" method instead of "executeAllActions".

Finally, let's consider the classroom example.

String expression = 
    "for(student : input.students){" +
    "	if(student.age < 10) return true;" +
    "}" +
    "return false;";

Rule r1 = new Rule("containsStudentUnder10", expression , "leaveEarly", 1, "ch.maxant.rules", "If a class contains a student under 10 years of age, then the class may go home early");
		
Rule r2 = new Rule("default", "true" , "leaveOnTime", 0, "ch.maxant.rules", "this is the default");
		
Classroom classroom = new Classroom();
classroom.getStudents().add(new Person(12));
classroom.getStudents().add(new Person(10));
classroom.getStudents().add(new Person(8));

Engine e = new Engine(Arrays.asList(r1, r2), true);
		
String outcome = e.getBestOutcome(classroom);

The outcome above is "leaveEarly", because the classroom contains one student whose age is less than 10. MVEL let's you write some pretty comprehensive expressions, and is really a programming language in it's own right. The engine simply requires a rule to return true, if the rule is to be considered a candidate for firing.

There are more examples in the JUnit tests contained in the source code.

So, the requirements are fulfiled, except for "It should be possible to store rules in a database". While this library doesn't support reading and writing rules to / from a database, rules are String based. So it wouldn't be hard to create some JDBC or JPA code which reads rules out of a database and populates Rule objects and passes them to the Engine. I haven't added this to the library, because normally these things as well as the management of rules is something quite project specific. And because my library will never be as cool or popular as Drools, I'm not sure it would be worth my while to add such functionality.

I've put the rule engine into an OSGi library with the LGPL licence and it can be downloaded from my tools site. This library depends on MVEL, which can be downloaded here (I used version 2.0.19). If you like it, let me know!

© 2011, Ant Kutschera

Social Bookmarks :

Java non-blocking servers, and what I expect node.js to do if it is to become mature

Sun, 22 May 2011 19:36:09 GMT

node.js is getting a lot of attention at the moment. It's goal is to provide an easy way to build scalable network programs, e.g. build web servers. It's different, in two ways. First of all, it brings Javacript to the server. But more importantly, it's event based, rather than thread based, so relies on the OS to send it events when say a connection to the server is made, so that it can handle that request.

The argument goes, that a typical web server "handles each request using a thread, which is relatively inefficient and very difficult to use." As an example they state that "Node will show much better memory efficiency under high loads than systems which allocate 2MB thread stacks for each connection."

They go on to state that "users of Node are free from worries of dead-locking the process — there are no locks. Almost no function in Node directly performs I/O, so the process never blocks. Because nothing blocks, less-than-expert programmers are able to develop fast systems".

Well, reading those statements makes me think that I have problems in my world which need addressing! But then I look at my world, and realise that I don't have problems. How can that be? Well first of all, because we don't have a thread per request, rather we use a thread pool, reducing the memory overhead, and queuing incoming requests if we can't run them in a thread instantly, until a thread becomes free in the pool.

The second reason I don't have threading problems is because I work with Java EE. I write business software which is written as components which get deployed to an app server. That app server is what does all the hard work with threads. All I have to do is follow some simple and common sense rules to avoid threading issues, like ensuring that shared resources like a Map(dictionary) are instantiated using the thread safe API which Java offers. In more extreme cases, I use the synchronized keyword to protect methods or objects being shared.

All this means that we Java programmers have become very efficient at writing software to solve business problems, rather than writing software to solve technical problems like concurrency, scalability, security, transactions, resources, object and resource pooling, etc., etc.

So when do I need to solve those problems which lots of threads introduce, namely memory problems? Any server which needs to maintain an open connection to the client, in order to say stream video or Voice over IP (VOIP), or handle instant messaging, is a server where I'm going to have problems with memory if I have a thread per connection.

Now, the Java EE specifications tend to focus on multithreaded servers. And to my knowledge, there is no Java EE specification which tells vendors how to make a server which lets people deploy software components to it, which are handled in a non-blocking manner. Sure, you could write a Servlet compliant server like Tomcat with a non-blocking engine under the hood, but Java EE doesn't talk about streaming. And probably 99% of websites out there don't do the kind of streaming which is going to cause memory issues.

So there certainly are times when something like node.js will be useful. Or at least the idea of a non-blocking server. But looking into the details, node.js isn't something that I would seriously use if I needed such a server. The main problems are that:

you deploy Javascript to the server
it doesn't seem to specify a standardised way of writing components so that I can concentrate on writing business software rather than solving technical issues
while it is rumoured to be fast, studies such as this suggest it's half as slow as Java
compared to Java, the node.js API and Javascript libraries available today are immature - think about things like sending email, ORM, etc.
node.js has political problems because it relies on Google. If Google don't want to support Javascript on the server (their V8 engine is designed for Chrome, client side), and node.js needs a patch or development on V8 to handle a serverside issue, they might never get it. OK, like I have a chance to get a Java bug patched by Oracle ;-)

It started for me, with this code snippet, taken from the node.js site:

    var net = require('net');

    var server = net.createServer(function (socket) {
      socket.write("Echo server\r\n");
      socket.pipe(socket);
    });

    server.listen(1337, "127.0.0.1");

Well, if the point of node.js is to make it really easy to create a server, and pass it a function for handling requests, I can do that in Java too:

TCPProtocol protocol = new TCPProtocol(){

    public void handleRequest(ServerRequest request, 
                              ServerResponse response) {

        //echo what we just received
        try {
            response.write(request.getData());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
};

Configuration config = new Configuration(1337, protocol);
ServerFactory.createServer(config).listen();

OK, it's a tiny bit more complicated. But the reason is, I decided to write a non-blocking server which can be configured to handle any kind of request. The configuration takes a port number for the server to run on, and a protocol object. The protocol object is a subclass of an abstract protocol, and its job is to look at the data coming in from the wire and decide how to handle it. A TCPProtocol as shown above is simplest protocol, in that it does nothing. You need to tell it what to do, by overriding the handleRequest() method (analagous to supplying a function in Javascript), for example as shown above, by returning to the client what it sent to the server.

But I wanted to do something more useful, so I extended what I wrote to handle voice over IP, or at least a client streaming an MP3 to a different client, to simulate a phone call between the two of them.

The first step was to design the protocol. At the byte level, the first byte in a packet sent to the server contains the command, or action, the second byte contains the length of the payload, if any, and the subsequent bytes contain the payload.

The protocol then lets a caller login (returning a session ID), start a call (returning an OK/NOK), send data for the call, end a call, and quit (logout).

After a few hours I had my laptop playing my favourite MP3s, streamed to my laptop from a different PC. But it looked clunky. I had a think, and took inspiration from the Servlet and EJB specifications in Java EE. Namely, I wanted to have deployable components whose sole job was to handle a business requirement.

In .NET and Java you can define a web service or web page (Servlet) by annotating the class. In the annotation, you provide a URL path, which the server uses to determine when to call your servlet or web service. This is similar to a "command" or "action" as I had in my VOIP protocol.

So I wrote a little container, which sits inside the non-blocking server. The server takes the incoming request and once it has handled the low level non-blocking stuff, it passes the request over to the configured protocol. The VOIP protocol then extracts the command (first byte) from the incoming request. It then uses a "context" object, which it gets injected into it from the container, to send the incoming request to a Handler. The handler is a class which has an annotation to state which command it can handle. The handler is then analagous to a web service or servlet. It is a piece of busienss code which handles an incoming request, based on the command (path) which the client is requesting.

Put together, it looks as follows. The first bit is the protocol's handler method which determines the command and sends it to a handler:

    public void handleRequest(ServerRequest request,
	                          ServerResponse response) {

        String criterion = String.valueOf(request.getData()[0]);
        try{
            //call through to the context for help - it
            //will call the handler for us.
            getContext().handleRequest(criterion, request, response);
        } catch (UnknownHandlerException e) {
            //send NOK to client because of unknown command
            response.write(new Packet(UNKNOWN_COMMAND).marshal());
        }
    }

A Packet object in the above code is simply an encapsulation of the data sent over the wire, but knows that the first byte is the command, the second is the length and subsequent bytes are the payload. In an HTTP request, this Packet object would be something which knew about the HTTP header's attributes and the HTTP payload, rather than the ServerRequest and ServerResponse objects which only know about byte arrays and sockets/channels.

The second part of the solution are then the handlers. These are contained in the configuration, either created programatically as shown in the TCP example above, or created using XML which the server reads upon startup. The container then locates, instantiates and calls these handlers on behalf of the protocol, when the protocol object calls getContext().handleRequest(criterion, request, response) in the above snippet. A typical handler looks like this:

@Handler(selector=VoipProtocol.LOGIN)
public class VoipLoginHandler extends VoipHandler {

    public void service(VoipRequest request,
                        VoipResponse response)
                        throws IOException {
		
        String name = request.getPacket().getPayloadAsString();
        Participant p = new Participant(
                        name, response.getSocketChannel());
        getProtocol().getModel().addParticipant(p);
        request.getKey().attach(p);
		
        //ACK
        String sessId = p.getSessId().getBytes(VoipProtocol.CHARSET);
        Packet packet = new Packet(sessId, VoipProtocol.LOGIN)
        response.write(packet);
	}

}

So, the service method is the only one in a handler, and is in charge of doing business stuff. There is no techy stuff here. The code works out who is logging in, creates an instance of them (the Participant object) in the model. The model is contained in the protocol object, which exists just once in the server. Compared to a servlet, the call to get the model is analagous to putting data into the application scope. The code then attaches the participant object to the client connection using the attach(Object) method (see Java NIO Package) so that we can always get straight to the relevant part of the data model from the connection object, when subsequent requests arrive. Finally, the code responds to the client with the session ID as an aknowledgement. Note that here, I haven't bothered to authenticate the password - the payload only contains the username. But if I were writing a complete app, I would have more data in my payload, perhaps even something like XML or JSON, and I would authenticate the username and password.

The @Handler annotation at the top of the handler class is analagous to the @WebServlet annotation applied to Java EE Servlets. It has a "selector" attribute which the container uses to compare to the criterion which the protocol extracts from the request. This is analagous to the URL patterns attribute in @WebServlet which tells a Java EE web container to which path the servlet should be mapped. There is a little bit of hidden magic too - the service method in the handler already knows VoipRequest and VoipResponse, rather than ServerRequest and ServerResponse. The superclass does this magic, by implementing the standard service method and calling the specialised abstract service method, implemented in subclasses.

So, being creative, I added a further attribute to the @Handler annotation. It is called runAsync and defaults to false. But, if it is set to true, then the container sends the handler to a thread pool for execution sometime in the future. I don't actually use this in the VOIP example, but I did this, to show that it is perfectly feasible, that an app server can do such things. The developer doesn't need to worry about threads or anything - they simple configure the annotation and the container handles the hard parts. This is typical of Java EE! And it becomes extremely useful in cases where a request needs a little more time to execute. In a non-blocking single threaded process, while connections are concurrently connected to the server, they are serviced sequentially, meaning that they MUST return fast, if you don't want those in the queue to wait too long. This is something which node.js CANNOT do, because it has no way of starting threads. Their solution is to send an async request to a different process. But to do that, the developer is spending time working on technical issues, rather than getting on and trusing the container to do it for them, so that they can spend more time writing cost effective business code. One of the main reasons to use Java EE is that the developer can spend more time writing business software and less time handling techie problems. There is no reason why a handler couldn't also have other annotations:

@Handler(selector=VoipProtocol.QUIT)
@RolesAllowed({"someRole", "someOtherRole"})
@TransactionManagement(TransactionManagementType.CONTAINER)
public class VoipQuitHandler extends VoipHandler {

    @PersistenceContext(unitName="persistenceUnitName")
    private EntityManager em;
    .
    .
    .
}

The @RolesAllowed@TransactionManagement annotation means that transactions will be handled by the container rather than by the programmer. When the handler is executed, the @PersistenceContext annotation causes the container to inject a JPA entity manager so that the business code has access to a database. This is exactly the same way that a Servlet or EJB gets resources from the container. Those resources are created based on the app server configuration, in a standardised way and are managed by the container too (pooling, reconnecting, etc.), again, relieving the programmer from that burden.

So what do we have now? Instead of a low level API like node.js provides, we have a high level container for running software components within a non-blocking server. What we don't have, is Javascript running on the server, because it seemed like the ideal language for handling callbacks in a non-blocking environment, because it has an event queue and function pointers.

Could this little exercise be the basis of a JSR? Well, is it really useful? Only really in cases where you have clients which need to keep connections open to the server for a long time, and you have thousands of clients. There won't be many people needing to do this, and there are more important JSRs awaiting acceptance and implementation. But who knows what the future will bring.

To summarise, node.js makes me uneasy, because I don't like the idea of Javascript and its immature stack of libraries being deployed on a production server. Whenever I develop with Javascript I spend a lot more time with the debugger than I would like to, because the language is not entirely checkable using static analysis because it is duck typed. But the idea of building a non-blocking server using Java - now that's interesting (to me at least). But like I said, I'm just not sure how often will it be useful.

It seems to me, that the revolution that node.js is starting isn't really about Javascript on the server. It is more about using a non-blocking server. But the problem is, probably 99% of our needs are already satisfied with standard multithreaded servers. And we can already write scalable websites, without all those problems which node.js claims we have. So let's not rebuild the world based on non-blocking I/O, just because node.js has arrived. Let's build/rebuild just those very special cases, where non-blocking I/O will really help us.

Does node.js deserve the hype it is getting? I don't think that it deserves hype because you can run Javascript on the server - that's a bad thing. Douglas Crockford (senior JavaScript architect at Yahoo!) even hints this, when he says:

"The big surprise for me in this is we're about to take maybe the most important step we've ever taken in terms of the technology of the web, and JavaScript is leading the way."

He seems to be saying that Javascript is leading the way in the most important step we are ever taking, and not that Javascript IS the most important step we are taking. That is, non-blocking servers are the most important step, and having an event loop on the server is the way forward. The way I understand it, he is saying that non-blocking is the revolution. The problem I have in joining in on this revolution is that non-blocking servers are not ncessarily the best thing ever. They only really help, when you have thousands of clients needing to keep their connections to the server open. HTTP (99% of the web) doesn't need non-blocking I/O to become the technology leader of the web - it already is. So instead of joining in this revolution and all the hype that node.js is stirring up, I will ignore it and continue building software the way I have been.

The code for the examples given above are in two Eclipse projects, which you can download here. The first project is the framework itself, including the non-blocking server, container and relevant classes and interfaces. The second project is an example of how to use the framework to build (business) apps. It contains the TCPServerRunner class for running a TCP echo server. It also contains the VoipServerRunner which starts the VOIP Server. To run the streaming example, first run the ListeningClient, followed by the SendingClient. Change line 74 of the SendingClient to use your favourite MP3, and you should hear it stream the first 20 seconds. The VOIP server itself isn't 100% reliable - especially once clients have disconnected. But I guess node.js wasn't that stable after only a small number of hours of development. Good luck!

PS. Performance: streaming at 192 kilobits a second, the server told me it was running around half a percent load (i.e. the event loop was idle 99.5% of the time). GSM, rather than high quality MP3 uses around 30 Kbps, so for a real VOIP server, you could probably get away with 1200 simultaneous calls. That doesn't seem that many, but I have no idea really. I guess I have 2 CPU cores which I could use so that I could use a load balancer to spread the load among two processes, which is the node.js way of using all the cores. But the load balancer wouldn't be doing much less work than my server does, so might not be able to handle any extra load itself. Or I could stick my handlers in a thread pool, using the runAsync attribute of my @Handler annotation. So a low cost commodity server could handle nearly 2500 simultaneous calls. Still not many? Again, I really don't know. But I should say that I didn't try optimising the server. My packet sizes are based on sending one packet of sound data every 12 milliseconds. Perhaps I could get away with sending them less frequently which might improve throughput and still have good call quality with low latency. Who knows - anyone wanting to optimise it, let me know the results! One thing for sure is that a server using one thread per connection with 2500 simultaneous connections, will struggle. While my previous blog article showed it is possible to have many thousand threads open, the context switching is likely to become the bottle neck. A non-blocking server is certainly the way forward for this use case.

Download the code here.

Copyright © 2011 Ant Kutschera

Social Bookmarks :

Node JS and Server side Java Script

Sat, 05 Mar 2011 21:36:00 GMT

Let's start right at the beginning. Bear with me, it might get long...

The following snippet of Java code could be used to create a server which receives TCP/IP requests:

class Server implements Runnable {
    public void run() {
        try {
            ServerSocket ss = new ServerSocket(PORT);
            while (!Thread.interrupted())
                Socket s = ss.accept();
                s.getInputStream(); //read from this
                s.getOutputStream(); //write to this 
        } catch (IOException ex) { /* ... */ }
    }
}

This code runs as far as the line with ss.accept(), which blocks until an incoming request is received. The accept method then returns and you have access to the input and output streams in order to communicate with the client.

There is one issue with this code. Think about multiple requests coming in at the same time. You are dedicated to completing the first request before making the next call to the accept method. Why? Because the accept method blocks. If you decided you would read a chunk off the input stream of the first connection, and then be kind to the next connection and accept it and handle its first chunk before continuing with the original (first) connection, you would have a problem, because the accept method blocks. If there were no second request, you wouldn't be able to finish off the first request, because the JVM blocks on that accept method. So, you must handle an incoming request in its entirety, before accepting a second incoming request.

This isn't so bad, because you can create the ServerSocket with an additional parameter, called the backlog, which tells it how many requests to queue up before refusing further connections. While you are busy handling the first request, subsequent requests are simply queued up.

This strategy would work, although it's not really efficient. If you have a multicore CPU, you will only be doing work on one core. It would be better to have more threads, so that the load can be balanced across the cores (watch out, this is JVM and OS dependent!).

A more typical multi-threaded server gets built like this:

class Server implements Runnable {
    public void run() {
        try {
            ServerSocket ss = new ServerSocket(PORT);
            while (!Thread.interrupted())
                new Thread(new Handler(ss.accept())).start();
                // one thread per socket connection every thread 
                // created this way will essentially block for I/O
        } catch (IOException ex) { /* ... */ }
    }
}

The above code hands off each incoming request to a new thread, allowing the main thread to handle new incoming requests, while spawned threads handle individual requests. This code also balances the load across CPU cores, where the JVM and OS allow it. Ideally, we probably wouldn't create a thread per new request, but rather hand off the request to a thread pool executor (see the java.util.concurrent package). On the other hand, there are times when a thread per request is required. If the conversation between server and client is longer lasting (rather than a simple HTTP request that is typically serviced in anything from milliseconds to seconds), then the socket can stay open. An example of when this is required are things like chat servers, or VOIP, or anything else where a continual conversation is required. But in such situations, the above code, even though it is multi-threaded, has it's limits. Those limits are actually because of the threads! Consider the following code:

public class MaxThreadTest {

    static int numLive = 0;
	
    public static void main(String[] args) {
        while(true){
            new Thread(new Runnable(){
                public void run() {
                    numLive++;
					
                    System.out.println("running " + Thread.currentThread().getName() + " " + numLive);
                    try {
                        Thread.sleep(10000L);
                    } catch (InterruptedException e) {
                        e.printStackTrace();
                    }

                    numLive--;
                }
            }).start();
        }
    }
}

This code creates a bunch of threads, until the process crashes. With 64 MB heap size, it crashed (out of memory) after around 4000 threads, while testing on my Windows XP Thinkpad laptop. I upped the heap size to 256 MB and Eclipse crashed while in debug mode... I started the process from the command line and managed to open 5092 threads, but it was unstable and unresponsive. Interestingly, I upped the heap size to 1 GB, and then I could only open 2658 threads... This shows, I don't really understand the OS or JVM at this level! Anyway, if we were writing a system to handle a million simultaneous conversations, we would probably need over two hundred servers. But theoretically, we could reduce our costs to less than 10% of that, because we are allowed to open just over 65,000 threads per server (well, say 63,000 by the time we account for all the ports used by the OS and other processes). We could theoretically get away with just having 16 servers per million simultaneous connections.

The way to do this is, is to use non-blocking I/O. Since Java 1.4 (around 2002?), the java.nio package has been around to help us. With it, you can create a system which handles many simultaneous incoming requests using just one thread. The way it works is roughly by registering with the OS to get events when something happens, for example when a new request is accepted, or when one of the clients sends data over the wire.

With this API, we can create a server, which is, sadly, a little more complicated than those above, but which handles lots and lots of sockets all from one thread:

public class NonBlockingServer2 {

	public static void main(String[] args) throws IOException {
		System.out.println("Starting NIO server...");
		Charset charset = Charset.forName("UTF-8");
		CharsetDecoder decoder = charset.newDecoder();
		CharsetEncoder encoder = charset.newEncoder();
		
		ByteBuffer buffer = ByteBuffer.allocate(512);

		Selector selector = Selector.open();
		ServerSocketChannel server = ServerSocketChannel.open();
		server.socket().bind(new InetSocketAddress(30032));
		server.configureBlocking(false);
		SelectionKey serverkey = server.register(selector, SelectionKey.OP_ACCEPT);

		boolean quit = false;
		while(!quit) {
			selector.select(); //blocks until something arrives, of type OP_ACCEPT
			Set keys = selector.selectedKeys();
			for (SelectionKey key : keys) {
				if (key == serverkey) {
					if (key.isAcceptable()) {
						SocketChannel client = server.accept();
						if(client != null){ //can be null if theres no pending connection
							client.configureBlocking(false);
							SelectionKey clientkey = client.register(selector,
									SelectionKey.OP_READ); //register for the read event
							numConns++;
						}
					}
				} else {
					SocketChannel client = (SocketChannel) key.channel();
					if (!key.isReadable()){
						continue;
					}
					int bytesread = client.read(buffer);
					if (bytesread == -1) {
						//whens this happen?
						key.cancel();
						client.close();
						continue;
					}
					buffer.flip();
					String request = decoder.decode(buffer).toString();
					buffer.clear();
					
					if (request.trim().equals("quit")) {
						client.write(encoder.encode(CharBuffer.wrap("Bye.")));
						key.cancel();
						client.close();
					}else if (request.trim().equals("hello")) {
						String id = UUID.randomUUID().toString();
						key.attach(id);
						String response = id + "\r";
						client.write(encoder.encode(CharBuffer.wrap(response)));
					}else if (request.trim().equals("time")) {
						numTimeRequests++;
						String response = "hi " + key.attachment() + " the time here is " + new Date() + "\r";
						client.write(encoder.encode(CharBuffer.wrap(response)));
					}
				}
			}
		}
		System.out.println("done");
	}
}

The above code is based on that found here. By reducing the number of threads being used, and not blocking, but rather relying on the OS to tell us when something is up, we can handle many more requests. I tested some code very similar to this to see how many connections I could handle. Windows XP proved its high reliability, when reproducibly and consistently, more than 12,000 connections lead to blue screens of death! Time to move to Linux (Fedora Core). I had no problems creating 64,000 clients all simultaneously connected to my server. Let me re-prase... I didn't have problems having the clients simply connect and keep the connection open, but getting the server to also handle just 100 requests a second caused problems. Now 100 requests a second on a web server, on hardware which was a 5 year old cheap Dell laptop, sounds quite impressive to me. But on a server with 64,000 concurrent connections, that means each client making a request every ten minutes! Not very good for a VOIP application... The connection speeds also slowed down from around 3 milliseconds with 500 concurrent connections, down to 100 milliseconds with 60,000 concurrent connections.

So, perhaps I better get to the point of this posting? A few days ago, I read about Voxer, and Node.js on The Register. I had difficulty with this article. Why would anyone want to build a framework for Javascript on the server? I have developed plenty of rich clients, and have the experience to understand how to do rich client development. I have also developed plenty of rich internet apps (RIA), which use Javascript, and I can only say, it's not the best. I'm not some script kiddie or script hacker who doesn't know how to design Javascript code, and I understand the problems of Javascript development well. And I have developed lots and lots of server side code, mostly in Java and appreciate where Java out punches Javascript.

It seems to me, that the developers of Node.js, and those following it and using it, don't understand server development. While writing in Javascript might initially be quicker, the lack of tools and libraries in comparison to Java make it a non-competition in my opinion.

If I were a venture capitalist, and knew my money was being spent on application development based on newly developed frameworks, instead of extremely mature technologies, when the mature technologies suffice (as shown with the non-blocking server code above), I would flip out and can the project.

Maybe though, this is why I have never worked at a start up!

To wrap up, let's consider a few other points. Before anyone says that the performance of my example server was poor because it's just Java which is slow, let me comment. First of all, Java will always be faster than Javascript. Secondly, using top to monitor the server, I noticed that 50% of the CPU time was spent by the OS working out what events to throw, rather than Java handling those requests.

In the above server, everything runs on one thread. To improve performance, once a request comes in, it could be handed off to a thread pool to respond. This would help balance load across multiple cores, which is definitely required to make the server production ready.

While I'm at it, here is a quote from Node JS's home page:

"But what about multiple-processor concurrency? Aren't threads necessary to scale programs to multi-core computers? Processes are necessary to scale to multi-core computers, not memory-sharing threads. The fundamentals of scalable systems are fast networking and non-blocking design—the rest is message passing. In future versions, Node will be able to fork new processes (using the Web Workers API ) which fits well into the current design."

Actually, I'm not so sure... Java on Linux can spread threads across cores, so individual processes are not actually required. And the above statement just proves that Node JS is not mature for building really professional systems - I mean come on, no threading support?!

So, in the interests of completion, here is the client app I used to connect to the server:

public class Client {

	private static final int NUM_CLIENTS = 3000;

	static Timer serverCallingTimer = new Timer("servercaller", false);
	
	static Random random = new Random();

	/**
	 * this client is asynchronous, because it does not wait for a full response before 
	 * opening the next socket.
	 */
	public static void main(String[] args) throws UnknownHostException, IOException, InterruptedException {
		
		final InetSocketAddress endpoint = new InetSocketAddress("192.168.1.103", 30032);
		System.out.println(new SimpleDateFormat("HH:mm:ss.SSS").format(new Date()) + " Starting async client");

		long start = System.nanoTime();
		for(int i = 0; i < NUM_CLIENTS; i++){
			startConversation(endpoint);
		}

		System.out.println(new SimpleDateFormat("HH:mm:ss.SSS")
				.format(new Date())
				+ "Done, averaging "
				+ ((System.nanoTime() - start) / 1000000.0 / NUM_CLIENTS)
				+ "ms per call");
	}

	protected static void startConversation(InetSocketAddress endpoint) throws IOException {
		final Socket s = new Socket();
		s.connect(endpoint, 0/*no timeout*/);
		s.getOutputStream().write(("hello\r").getBytes("UTF-8")); //protocol dictates \r is end of command
		s.getOutputStream().flush();

		//read response
		String str = readResponse(s);
		System.out.println("New Client: Session ID " + str);

		//send a request at regular intervals, keeping the same socket! eg VOIP
		//we cannot use this thread, its the main one which created the socket
		//simply create another task to be carried out by the scheduler at a later time

		//the interval below is 4 minutes, otherwise the server gets REALLY slow handling 
		//so many requests.  This is equivalent to ~260 reqs/sec
		
		serverCallingTimer.scheduleAtFixedRate(
				new ConversationContainer(s, str), 
				random.nextInt(240000/*in the next 4 mins*/), 
				240000L/*every 4 mins*/);
	}
	
	private static String readResponse(Socket s) throws IOException {
		InputStream is = s.getInputStream();
		int curr = -1;
		ByteArrayOutputStream baos = new ByteArrayOutputStream();
		while((curr = is.read()) != -1){
			if(curr == 13) break; //protocol dictates a new line is the end of a response
			baos.write(curr);
		}
		return baos.toString("UTF-8");
	}

	private static class ConversationContainer extends TimerTask {
		Socket s;
		String id;
		public ConversationContainer(Socket s, String id){
			this.s = s;
			this.id = id;
		}
		
		@Override
		public void run() {
			try {
				s.getOutputStream().write("time\r".getBytes("UTF-8")); //protocol dictates \r is end of command
				s.getOutputStream().flush();

				String response = readResponse(s);
				
				if(random.nextInt(1000) % 1000 == 0){
					//we dont want to log everything, because it will kill our server!
					System.out.println(id + " - server time is '" + response + "'");
				}
				
			} catch (Exception e) {
				e.printStackTrace();
			}
		}
	}
}

Social Bookmarks :

DCI and Services (EJB)

Sat, 20 Nov 2010 21:29:00 GMT

Data, Context and Interaction (DCI) is a way to improve the readability of object oriented code. But it has nothing specific to say about things like transactions, security, resources, concurrency, scalability, reliability, or other such concerns.

Services, in terms of stateless EJBs or Spring Services, have a lot to say about such concerns, and indeed allow the cross-cutting concerns like transactions and security to be configured outside of the code using annotations or deployment descriptors (XML configuration), letting programmers concentrate on business code. The code they write contains very little code related to transactions or security. The other concerns are handled by the container in which the services live.

Services however, constrain developers to think in terms of higher order objects which deliver functionality. Object orientation (OO) and DCI let programmers program in terms of objects; DCI more so than OO. In those cases where the programmer wants to have objects with behaviour, rather than passing the object to a service, they can use DCI.

If objects are to provide rich behaviour (ie. behaviour which relies on security, transactions or resources), then they need to somehow be combined with services, which naturally do this and do it with the help of a container, so that the programmer does not need to write low level boiler plate code, for example to start and commit transactions.

The idea here, is to explore combining a service solution with a DCI solution. Comparing SOA to DCI, like I did in my white paper, shows that the DCI context is analagous to the code which calls a service in a SOA solution, and that a context does not really explicitly exist in a SOA solution. However, thinking a little more abstractly, in DCI an encapsulation of behaviour would be the context together with its roles. In SOA, this encapsulation is the service itself. So it is possible to realign the ideas in that white paper, to think of a context as being a service. If the goal is to create a hybrid between services and DCI, so that all of the concerns listed at the start of this article get handled by a hybrid solution, then the roles still exist as they do in DCI, but the context becomes a "service" in the technical sense.

Time for an example. Imagine a train company which owns electrified tracks along which trains run. They have a business partner who provides the electrical energy, who is offering cheaper energy to consumers who can forecast their energy consumption so that the partner can make their production more efficient. To deliver these forecasts, the train company checks the timetable for regular passenger transport, as well as all its cargo contracts for bespoke cargo trips. This allows them to simulate all train trips for a given time period and calcuate the energy requirement. Now, the company is a national one, and has thousands of kilometers of track and hundreds of trains running. They have created detailed maps of the terrain over which their tracks run, so they know the uphill and downhill segments and their power consumption changes. They want to build some simulation software to handle the forecasting. At the same time, there is a non-functional requirement to complete calculations extremely quickly, so rather than making them sequential, a parallel solution is required. Here is the proposed object model:

Trip: Consists of a Train and a list of TripSegments.
Train: consists of a list of Locomotives, and a list of Wagons. The assembly of a train comes from the Timetable.
Locomotive: Has an efficiency, a weight and rolling friction factor.
Wagon: has a weight and rolling friction factor.
TripSegment: has a Segment, and the average speed along which the Train will travel on that segment, during its trip.
Segment: a stretch of track, which has a length, positive hill climbs and negative hill decents. Has a starting station and an end station, which are not relevant to the energy calculations - it is the distance which counts.
Timetable: a service which provides all Trips for a given time period.

In order to make each trip be calculated in parallel, I have chosen to use a feature of EJB whereby the container creates a new thread and does the calculation on that thread. It means with a simple annotation on a method, I have almost no boiler plate code to write! In order to use that annotation, my context needs to be an EJB, but seeing as the application is running in an enterprise Java application server anyway (so that I can for example have a nice website as a front end), this is no big deal.

So, the architecture of this solutions is: a web request to run the calculation is received which makes a call to my process layer (aka application layer). The process layer calls the timetable to get all trips for the requested period, and for each trip it calls the context to do a calculation in parallel. The process layer waits for all calculations to complete and returns the result to the web layer to present the results to the user. Here is the context:

@Stateless
@Context
public class ForecastingContext implements ForecastingContextLocal {

	/**
	 * an asynchrounous method for determining the energy requirements of the given trip.
	 */
	@Asynchronous
    public Future forecastEnergyRequired(Trip trip) {

		BehaviourInjector bi = new BehaviourInjector(this);
		
		//the context simply casts objects into roles, and starts the interaction
		EnergyConciousTrip t = bi.assignRole(trip, EnergyConciousTrip.class);
		double energy = t.forecastEnergyRequirements();
		
		return new AsyncResult(energy);
    }
}

The context does nothing special, apart from contain the @Asynchronous annotation which tells the container that calls to this method need to occur on a new thread. Unlike perhaps more standard DCI, this context has no constructor which takes objects which will play roles, rather the interaction method "forecastEnergyRequired" is passed the object which gets cast into a role. The reason is that I have no control over the instantiation of the context, because it is an EJB, meaning that the container does the instantiation for me!. I have not sub-classed BehaviourInjector (which is an option in my framework), because stateless EJBs can be called by multiple threads at the same time, and BehaviourInjector is not thread safe.

Here are the two roles:

/**
 * this role is played by a trip so that it is able to 
 * give a prediction about how much energy will be 
 * needed to undertake the trip.
 */
@Role(contextClass=ForecastingContext.class, 
		implementationClass=EnergyConciousTrip.EnergyConciousTripImpl.class)
public interface EnergyConciousTrip {

	double forecastEnergyRequirements(); //role
	List getTripSegments(); //data
	Train getTrain(); //data
	
	static class EnergyConciousTripImpl{ //role implementation
		
		@CurrentContext
		private IContext ctx;
		
		@Self
		private EnergyConciousTrip self;

		/**
		 * energy consists of a longitudinal component (ie along the track due to 
		 * aerodynamic forces and rolling resistance) as well as altidudal component
		 * (ie due to climbing or descending).
		 * 
		 * E = mgh //ie potential energy for climbing / descending
		 * E = Fd  //ie energy required to overcome resistive forces
		 */
		public double forecastEnergyRequirements(){
			
			//give the train some scientific behaviour and determine
			//its total weight and average efficiency
			ScientificTrain train = ctx.assignRole(self.getTrain(), ScientificTrain.class);
			double totalWeight = train.getTotalWeightKg();
			double avgEff = train.getAverageEfficiency();
			
			//add up all energy per segment
			double energy = 0.0;
			for(TripSegment seg : self.getTripSegments()){
				
				double segmentEnergy = train.getResistanceForce(seg.getSpeed()) * seg.getSegment().getLengthMeters();
				
				segmentEnergy += totalWeight * seg.getSegment().getAltitudeChange();
				
				//each locomotive can pull, but has an efficiency which needs to be factored in!
				//it needs more energy than just pulling wagons, because its inefficient
				segmentEnergy /= avgEff;
				
				energy += segmentEnergy;
			}
			
			return energy;
		}
	}
}


/**
 * played by a train, when it needs to provide scientific details about itself.
 */
@Role(contextClass=ForecastingContext.class,
		implementationClass=ScientificTrain.ScientificTrainImpl.class)
public interface ScientificTrain {

	double getResistanceForce(double speed); //role
	int getTotalWeightKg(); //role
	double getAverageEfficiency(); //role
	List getWagons(); //data 
	List getLocomotives(); //data
	double getDragCoefficient(); //data
	
	static class ScientificTrainImpl { //role impl

		@Self
		private ScientificTrain self;

		/** 
		 * resistance force is the rolling friction as a 
		 * result of weight, as well as aerodyamic drag.
		 */
		public double getResistanceForce(double speed){
			double resistanceForce = 0.0;
			for(Wagon w : self.getWagons()){
				resistanceForce += w.getWeightKg() * w.getRollingFriction();
			}
			for(Locomotive l : self.getLocomotives()){
				resistanceForce += l.getWeightKg() * l.getRollingFriction();
			}
			
			resistanceForce += speed * speed * self.getDragCoefficient();
			
			return resistanceForce;
		}

		/** total weight of wagons and locs. */
		public int getTotalWeightKg(){
			int weight = 0;
			for(Wagon w : self.getWagons()){
				weight += w.getWeightKg();
			}
			for(Locomotive l : self.getLocomotives()){
				weight += l.getWeightKg();
			}
			return weight;
		}

		/** average of all locs in the train */
		public double getAverageEfficiency(){
			double avg = 0.0;
			for(Locomotive l : self.getLocomotives()){
				avg += l.getEfficiency();
			}
			return avg / self.getLocomotives().size();
		}
	}	
}

There is nothing fancy in these roles - simply the engineering calculations to work out the energy requirements. I have chosen to implement the role implementations inside the role interface, but there is no reason the role implementations could not exist in their own classes.

Finally, here is the process layer:

@Stateless
public class EnergyForecastingService implements EnergyForecastingServiceLocal {

	@EJB
	private TimetableLocal timetable;

	@EJB
	private ForecastingContextLocal forecastingContext;
	
	@Override
	public EnergyRequirementResult forecast() throws InterruptedException, ExecutionException {
		
		long start = System.nanoTime();
		List> results = new ArrayList>();
		EnergyRequirementResult result = new EnergyRequirementResult();
		result.setTrips(timetable.getTripsForPeriod(null, null));
		for(Trip trip : result.getTrips()){
			//start it in a parallel thread
			//it will be simulated using a DCI context...
			Future e = forecastingContext.forecastEnergyRequired(trip);
			results.add(e);
		}
		
		//ok, all started, lets wait until all are done...
		result.setEnergyRequirement(waitForResults(results));
		result.setCalculationTimeNs(System.nanoTime() - start);
		
		return result;
	}

	private double waitForResults(List> results) throws InterruptedException, ExecutionException {
		double energyRequired = 0.0;
		while(!results.isEmpty()){
			List> assimilated = new ArrayList>();
			for(Future result : results){
				if(result.isDone()){
					assimilated.add(result);
					energyRequired += result.get().doubleValue();
				}
			}
			results.removeAll(assimilated);
			
			//lets give CPU time to other threads while we wait...
			Thread.sleep(5L);
		}
		
		return energyRequired;
	}
}

The process layer uses these funny "Future" objects which allow it to not only get the result from a calculation which has run on another thread, but also to query whether that thread has completed or is still running. The only boiler plate code needed to handle this multi-threaded code is analysis of results while waiting for them all to complete.

The context and its roles look like this:

One interesting side point, is that the EnergyRequirementResult is a class in the context's package (namespace), because it only makes sense to create it from the context. It can be used outside of the context as a read only object to read the results, but it is strongly coupled to the context. It doesn't really make sense for it to exist without the context, and thinking in terms of components, or code re-use, it makes sense to place it in the same namespace as the context. The context and its roles, are afterall a component which can calculate energy requirements - they encapsulate the behaviour to do this.

It might look strange that the behaviour is not simply added to the train and trip objects. But it's hard to see the benefits when looking at such a small project. Imagine a huge project where the object model is much more complex, and there are many many more use cases. If you look at the object model in this example, the train and timetable can be used in many more applications than just one which does energy predictions. Typically within an enterprise, we keep rebuilding similar object models with relevant parts of data, and differing behaviours for each OO solution. DCI lets you build a large single object model, with behaviours constrained to the contexts in which they are relevant. This allows the data model to become sufficiently complex to make it usable within the entire enterprise, but not so overly complex that making changes to it breaks it. Of course it is also arguable, that things like drag coefficients and rolling friction coefficients have no place in an object model of an application related to passenger load planning or whatever else the enterprise needs to do. In terms of making applications flexible to change, it can help if each application has its own object model, even if it results in code duplication within the enterprise.

In this example I have turned my context into an EJB, because I want to take advantage of boilerplate code which the container can handle for me - in this case concurrent computing. Similarly, if my context needs resources, transactions, security, etc, I would use an EJB for my context, and pass the resources which the container injects into it, into the roles using my BehaviourInjector framework (see its documentation for details). I have solved the banking example used in many DCI articles, by making the contexts EJBs, letting the container handle transactions, and getting hold of the EntityManager (for interacting with the database) by letting the container inject it into the context, which the BehaviourInjector can in turn inject into roles.

If contexts are to be "services" in the technical sense, it also makes sense for an enterprise to build a context repository to sit along side their service repository. These are places for software people to look, when needing to see if problems they face have already been solved. Just as we have tools for searching service repositories and we create documents to list all our services, we will need to do the same for contexts, if DCI is to really be adopted by the enterprise world.

It's important to remember that you could build this solution with pure services, or pure OO. DCI is simply another, and valid way of solving the problem, which concentrates on separating the behaviour from the data in order to make the code more reviewable, while at the same time remaining object oriented, so that the model which the users and customers have, stays similar to that which the programmer uses. Is creating roles and injecting behaviour into the Train and Trip objects better than putting those methods into a service which does the same thing? I don't know... It is certainly less OO, but is that a bad thing? Perhaps its just down to designers choice and feeling comfortable with the resulting code. So long as reading the solution compares to the users and customers stories, that is the important thing. Mappings between the users/customers world, and the programmers world are unnecessary and cause bugs as well as unsatisfactory users, because the programmer concentrates on solving his problems, rather than the business' problems.

You can download all the source code for this train app from here.

PS. I have no idea if train companies need to forecast energy requirements, or even if they work with energy partners. The creativity of this blog article should not hamper the readers understanding of how to create a service/DCI hybrid, in order to benefit from the way a container handles the concerns listed at the start of this article!

© 2010 Ant Kutschera

Social Bookmarks :