The Kitchen in the Zoo - dci tag

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 :

DCI Plugin for Eclipse

Tue, 16 Nov 2010 20:58:00 GMT

The Data, Context, and Interaction (DCI) architecture paradigm introduces the idea of thinking in terms of roles and contexts. See some of my white papers for a more detailed introduction into DCI, but for this blog article, consider the following example: a human could be modelled in object oriented programming by creating a super huge massive class which encapsulates all a humans attributes, their behaviours, etc. You would probably end up with something much too complex to be really maintainable. Think about when a human becomes a clown for a kids party; most of that behaviour has little to do with being a programmer, which is a different role which the human could play.

So, DCI looks at the problem differently than OOP and solves it by letting the data class be good at being a data class, and putting the behaviours specific to certain roles into "roles", which in my DCI Tools for Java library are classes.

Certain roles interact with each other within a given context, such as a clown entertaining kids at a birthday party. The roles which belong to an interaction are part of the context, and in DCI the context is a class which puts data objects into specific roles, and makes them interact. The context and its roles form the encapsulation of the behaviour.

I have updated my library, so that there are two new Annotations, namely the @Context and @Role annotations. The @Context annotation is simply a marker to show that a class is a context. The @Role annotation is more important. It is placed onto the role interface class and tells the context where to find the role implementation, and additionally requires that the programmer specifically state to which context the role belongs.

The code ends up looking looking as follows. First a unit test which creates and calls the context:

    @Test
    public void testExecute() {
    	
    	//create an adult (the clown) and some children, 
    	//and let the party start...
        
    	Human adult = new Human();
        List children = new ArrayList();
        Human child = new Human();
        child.setName("Johnny");
        children.add(child);
        child = new Human();
        child.setName("Jane");
        children.add(child);

        ClownContext cc = new ClownContext(adult, children.toArray());
        cc.startParty();

        //check the party went well...
        assertEquals(0, adult.getHappiness());
        for (Human c : children) {
            assertEquals(1, c.getHappiness());
        }
    }
}

There is nothing special about the code above. It simply creates some data objects and passes them to the context, and then starts the party (the interaction, or use case). Next, the context class is shown:

/** the context in which a clown entertains some kids. */
@Context
public class ClownContext extends BehaviourInjector {

    /** the object who will play the clown role */
    private Object adult;
    
    /** the objects who will play the kid role */
    private List children;

    /**
     * Creates a new Context object. takes "objects" rather than specific types to allow it to be reusable.
     */
    public ClownContext(Object adult, Object[] children) {
        this.adult = adult;

        this.children = new ArrayList();

        for (Object child : children) {
            this.children.add(child);
        }
    }

    /** start the interaction */
    public void startParty() {
        Clown clown = assignRole(adult, Clown.class);
        
        clown.applyMakeup();

        IIterable kids = getIterable(children.iterator(), Kid.class);

        clown.makeKidsLaugh(kids);
    }

}

The context has a few noteworthy points. First of all, it extends the BehaviourInjector. By doing this, it has access to the assignRole(Object, Class) and getIterable(Iterator, Class) methods. Note the @Context annotation at the top - it's important for not only helping the programmer spot that it's a context, but also for the Eclipse plugin which I created and which I introduce below.

You might have spotted that the context above is not tightly coupled with the Human class. The reason is simply to make the context and its roles usable in the future, with data classes which I currently know nothing about. It is feasible that a robot might one day do parties by dressing up as a clown!

Assigning the role is where the behaviour is "injected" into the data object. The iterable which is created is a special role, which can automatically cast the human children into the role of a kid attending a party.

Next, take a look at the role interface. This class defines the methods which data object must have to play the role, as well as the behaviour which will be added to the object.

@Role(contextClass = ClownContext.class, 
	  implementationClass = ClownImpl.class)
public interface Clown {

	/** put some makeup on (initialise) */
	public void applyMakeup(); // role

	/** makes kids laugh */
	public void makeKidsLaugh(IIterable kids); // role
	
	public void setHairColour(Color c); // data
	
}

The role interface has the @Role annotation which tells the behaviour injector firstly to which context the role belongs, and secondly where the actual implementation (behaviour) can be found. In the clown role specified above, two behaviours are added (applying make up and making kids laugh). The application of make up additionally requires that the clown be able to set his hair colour, so that method which the human class must have is also specified here.

Finally, the role implementation class:

public class ClownImpl {

	@Self
	private Clown self;
	
	/** @see Clown#applyMakeup() */
	public void applyMakeup(){
		self.setHairColour(Color.GREEN);
	}

	/** @see Clown#makeKidsLaugh(IIterable) */
	public void makeKidsLaugh(IIterable kids) {
		for (Kid kid : kids) {
			kid.laugh();
			System.out.println();
		}
	}
}

The role implementation does not need to implement the role interface! It is simply a class which the behaviour injector relies upon to find behaviour which it cannot find in the data object. The @Self annotation on the clown field called self is a reference to the object playing the clown role, and is similar to "this", just that "this" would be a reference to the instance of the role implementation, rather than the object playing the role. It allows you to access the data methods of the data object.

Now, as well as helping the programmer to mentally associate contexts with roles, these two annotations allow static analysis of the code to be performed. Using the Eclipse JDT framework, it is possible to obtain individual tokens of source code, even when the class files don't compile, in order to build up a model of contexts and roles within a Java project. I created a little DCI Outline view for Eclipse, similar to the class outline, except rather than showing classes, it shows the contexts and their associated roles. Here's a screen shot:

The view shows all contexts which it finds in the selected Java project. For each context, it shows the package, followed by a list of its methods, and then all the roles that belong to it.

For each role interface, the package is listed, followed by a list of methods which the role interface contains. At the bottom of a role branch, is the role implementation class.

The idea of this plugin is to give the programmer a view of what contexts are available and what roles they contain. It puts contexts, roles and their methods into the mind of the programmer letting them think in terms of DCI, exactly the same way which a standard class browser lets the programmer think in terms of classes.

Double clicking on a role interface, role implementation or context will open it in the editor.

The plugin has limited validation capabilities and can determine for example, if a context specified in a role annotation cannot be found within the project, and highlights this so that the programmer can see there is a problem. In such cases, the view looks like this:

The code from this example can be downloaded here.

A full instruction manual, together with the the DCI Tools for Java library, and the Eclipse Update site can be found at here.

Attention: No clowns were harmed during the writing of this blog.

© 2010 Ant Kutschera

Social Bookmarks :