Tuesday, April 23, 2013

Extend interface implementation (proxy/delegation pattern)

Yes this is not a type mistake, I want to extend the implementation of an interface. How many times do we have access to an interface but not the implementation? In the case that we have the implementation we can usually inherit the class and override the public/protected functionality. But what do you do when there is a factory builder that returns an instantiated object with an interface and you do not know or what to know the implementation (since it can always change), and you still want to override some of the functionality.

Let’s take a simple example. To write an xml file you can use the following code:

Object request;

JAXBContext jc = JAXBContext.newInstance(classesToBeBound);

Marshaller m = jc.createMarshaller();

XMLOutputFactory xmlOutputFactory = XMLOutputFactory.newInstance();

ByteArrayOutputStream ba = new ByteArrayOutputStream();

XMLStreamWriter writer = xmlOutputFactory.createXMLStreamWriter(ba);

m.marshal(request, writer);

This code takes a buffer array and marshals it to an xml document using the XMLStreamWriter.

The XMLStreamWriter is an interface:

public abstract interface javax.xml.stream.XMLStreamWriter

with function for writing xml documents like: writeStartElement, writeEndElement.

As we know there are characters in xml that cannot be written to the string document since they are used by the xml format. The characters are: [&<>'\”]. To overcome this when writing the xml for example, the > will be changed to >. There are some systems that do not know how to read this string. For these systems there is the CDATA format (see http://xml.silmaril.ie/specials.html). A CDATA section is a string that starts with <![CDATA[ and ends with ]]>. Within this string you can write any text you want, for example:

<![CDATA[<sender>John Smith</sender>]]>

This is a legal text that will not be read as a xml mockup, but will be read as: <sender>John Smith</sender>

Back to our case. Let’s say that we want to convert some of the text to CDATA but the XMLStreamWriter does not support this. We would like to override the function of writeCharacters. So how do we override an interface implementation? There are two way that are more or less the same, but one is more explicit and the other generic.

We will start with the specific solution. An interface is a contract that specifies an api without the implementation. The factory builder returns the interface with a specific implementation behind it. What we do is create a new class that holds a reference to the current instance and implements the interface. The all methods are delegated to the internal reference, and those methods that we want to override we can. For example (not a full class implementation):

public class DelegatingXMLStreamWriter implements XMLStreamWriter {

XMLStreamWriter delegate;

public DelegatingXMLStreamWriter(XMLStreamWriter del) {

delegate = del;

}

public void close() throws XMLStreamException {

delegate.close();

}

public void flush() throws XMLStreamException {

delegate.flush();

}

public void writeCharacters(char[] arg0, int arg1, int arg2) throws XMLStreamException {

delegate.writeCharacters(arg0, arg1, arg2);

}

As you can see all that the class does is to delegate all functionally to the instance that was created by the factory, and specific implementations can be override (This class is a helper class that can be found at http://java.net/projects/stax-utils/pages/Home).

The second way to do this is not to explicitly write a class that delegates all the methods (they can be tens of methods), but to create a proxy object and the catch only the one method that needs to be overridden:

XMLStreamWriter proxyXMLStreamWriter = (XMLStreamWriter)Proxy.newProxyInstance(XMLStreamWriter.class.getClassLoader(),new Class[] { XMLStreamWriter.class },new InvocationHandler() {

@Override

public Object invoke(Object arg0, Method arg1, Object[] arg2) {

if(method.getName().equals("writeCharacters") {

// override specific method with functionality

}

});

}

Summary:

As you can see it is fairly easy to add functionality even to a class that you do not have the source code for. This is done using the proxy/delegation pattern.

Monday, April 8, 2013

Soap Model Duplication / Mitigation

When creating a soap interface (or any other external api) after you already have a very big internal model base can be very difficult.

The optimal architectural design is to have two model bases one internal and one external. The reason for this is to decouple internal code from external. Usually the external interface does not change much and refactoring is not an option (since the clients are already using this interface). On the other hand internal structures are always being refactored to meet new requirements. If the subset functionality needed to be exported is well defined, then the decision is usually strait forward, since the external api by requirement will be different from the internal.

The problem is that if your model is very big and the requirement are to export all internal functionally then we have the problem of duplicating the full model (which can be tens if not hundreds of classes).

In any case when having a dto we need a simple way to covert from the external api to the internal and vice versa.

When looking from above there are two major options (in the case of xml based protocols). In the case of soap the protocol is based on xml documents. So any request is converted from xml to an object and then the result is converted from the object back to xml.

So if we need to transform the request from the external api to the internal api, we can either do it on the object level or on the xml level.

The object level is the more known way to do conversions since it is not protocol specific, and can be done on the external level in code. The disadvantage is that the transformations are not always easy and need an external framework to help (see http://dozer.sourceforge.net/). Another disadvantage is that the code becomes very “dirty” with a lot of lines just for the transformation.

Another option that I want to expand on is the option for transformation on the xml level. Since the protocol of soap is based on xml and xsd schemes, there is an option of transforming the incoming and outgoing xml using xslt. Xslt is widely known and has a lot of transformation capabilities (http://www.w3schools.com/XSL/).

In this solution you have only one model base and do the transformations on the xml level and not on the object level.

Using a framework like CXF (http://cxf.apache.org/) for soap, it is very easy to add xslt files for your soap requests.

The way CXF works, is that for every incoming and outgoing request there is a list of interceptors that are called. The message is sent to each interceptor (order can be set) in the chain before and after. So the soap request will pass through the interceptors, and one of them will do the transformations.

CXF supports two types of transformations: StaxTransformFeature, XSLTFeature.

The difference between the two, I copied from the site of CXF (http://cxf.apache.org/docs/xslt-feature.html):

When should I use Transformation Feature and when XSLT Feature?

If only trivial transformations must be done, it is recommended to use lightweight and fast Transformation Feature. It covers the most use cases as:

· dropping the namespace of the outbound messages;

· qualifying the incoming message;

· changing namespaces;

· appending or dropping elements;

· converting attributes to elements.

Transformation Feature is completely stream oriented and work fast especially for large messages.

If you should apply non-trivial transformation, not supported by Transformation Feature - it is use case for XSLT Feature. Here you can write any custom XSL Transformation and apply it to inbound and/or outbound messages.
As far as Xalan XSLT engine is actually not completely stream oriented, XSLT Feature breaks streaming. However it uses high-performance DTM (Document Table Model) instead complete DOM model.
Performance can be improved in the future by using further versions of Xalan or other XSLT engines (like Saxon or STX oriented Joost).

I will describe how to use the XSLTFeature since we need a full xsl file to transform the requests.

In the application context of the CXF where you define your endpoints you need to define the following:

</bean>

<jaxws:endpoint implementor="#soapTestService" address="/ws/SoapTestService">

<jaxws:features>

</jaxws:features>

</jaxws:endpoint>

The first bean is what the interceptor will use. You need to create one per endpoint, since this bean will hold the in and out xls. Then on your endpoint you add the jaxws:features with a reference to your bean.

This will cause the CXF to run the transformers on the incoming message and the outgoing message.

To start testing this you can use a simple xsl that actually just copies the original xsl:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:sapiens="http://soap.interfaces.internal.foundation.alis.sapiens.com/">

<xsl:template match="@*|node()">

<xsl:copy>

<xsl:apply-templates select="@*|node()" />

</xsl:copy>

</xsl:template>

</xsl:stylesheet>

Then to easily remove a specific property from the xml you can write:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:sapiens="http://soap.interfaces.internal.foundation.alis.sapiens.com/">

<xsl:template match="@*|node()">

<xsl:copy>

<xsl:apply-templates select="@*|node()" />

</xsl:copy>

</xsl:template>

<xsl:template match="msgText">

</xsl:template>

</xsl:stylesheet>

This will remove the xml element of msgText from the xml.

As you can see it is very easy to remove attributes or nodes from the soap xml model, or to do any transformation that you need on the xml level, and not on the object level.

Wednesday, March 20, 2013

Automatic API Documentation

Documentation of API is always needed. Some protocols and standards support better documentation then others. Soap for instance supports better documentation than rest, but still needs explicit documentation so that clients can know how to use it.

Rest is known as a more problematic protocol since it is not self-documented.

Another issue is of course the problem that the code changes often after the spec has been written.

For this there a frameworks that create documentation from your code, and can be a part of your site.

This way the documentation is up to date and is available at all times.

There are multiple frameworks that do this. A list are:

http://enunciate.codehaus.org/

https://developers.helloreverb.com/swagger/

http://rubygems.org/gems/calamum

In this blog I will describe the enunciate framework, since this framework give a rich output, and covers multiple protocols, including the option to generate client code in multiple languages to consume the rest api.

The current downside of enunciate is its documentation that is very sparse. So I will show you how to get a site up and running.

Many frameworks use proprietary annotations for the documentation which can be a hindrance if you want to change the framework. Enunciate used javadoc that is above your rest interface for documentation. It is a pity that they do not support the annotations that are part of JAX-RS (like @Description)

For example:

/**

* Gets the location.

* @param location free text location including all fields (street, city)

* @return the location after it has been enriched

* @throws ServiceInternalException the service internal exception

@GET

@Path("/lookup/simple/{location}")

LocationLookupResult getLocation(@Description("String of location, your may enter the full address in one string")@PathParam("location") String location);

The result will be:

Enunciate can be run from the command line, or be added to you maven project.

<groupId>org.codehaus.enunciate</groupId>

<artifactId>maven-enunciate-cxf-plugin</artifactId>

<goals>

</goals>

<docsDir>${project.build.directory}/docs</docsDir>

<configFile>./src/main/resources/enunciate.xml</configFile>

</configuration>

</execution>

</executions>

</dependencies>

</plugin>

The secret to configuring enunciate is the enunciate.xml file, you need to configure this file properly for it to work, and all configuration is done in this file, for example:

<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="

http://enunciate.codehaus.org/schemas/enunciate-1.26.xsd"

label="Alis Documentation">

<api-import pattern="com.mycompany.interfaces.*" />

<api-import pattern="com.mycompany.interfaces.soap.*" />

</rest>

</services>

<disable-rule id="csharp.warnings" />

<disable-rule id="c.warnings" />

<disable-rule id="obj-c.warnings" />

<docs docsDir="api" title="ALIS API" includeDefaultDownloads="true" includeExampleXml="false"

disableRestMountpoint="true" copyright="copyright" forceExampleJson="true">

</docs>

<basic-app disabled="true" />

<jaxws-ri disabled="true" />

<obj-c disabled="true" />

<java-client disabled="true" />

<jaxws-client disabled="true" />

<jaxws-support disabled="false" />

<spring-app disabled="false" mergeWebXML="./src/main/webapp/WEB-INF/web.xml">

</spring-app>

</modules>

</enunciate>

You can have enunciate create a site or you can merge enunciate into your own site. Enunciate supports of course jax-rs with cxf jersy or spring.

The result of the enunciate process is a folder in your target folder.

If you want to add this manually to your site you need to configure the maven-war-plugin to include the following folders: docs/, docs/css, docs/js (assuming your folder is docs, defined in the maven-enunciate-cxf-plugin).

Tuesday, March 5, 2013

ThreadLocal and WeakReference

Let’s say we have a service that does some processing. This service needs to support multithreading, and there is some additional information that needs to be saved along the main process.

For example, I have a dao service. This service in addition to saving the entity, knows to save the full graph of the entity. What I need in the end of an action (update) is a list of all entities that where effected. Since this service is a singleton and multiple threads will be calling the same update function I need to save this information somewhere.

One option is to pass a callback, but that is not very nice. Since the saving calls multiple functions, I will need to pass the callback to all function, or refactor to move all code to a class that will be created for the processing.

A second option is for the calling thread to register a list (not part of the calling function, but a separate one), and for the service to fill that list with all the changes. The list itself will be stored on the ThreadLocal, and then multiple threads can run with no problem. The problem now is, how can I make sure that the calling thread will unregister the list so that the memory will be released?

The simple solution for this is not to store a pointer to the list itself on the local thread, but to use a weak reference. This will hold a pointer to the list, but will not be counted as a holding pointer as far as the garbage collection is concerned. This means that once the client calling thread will leave scope the allocated list will be garbage collected, and then the local thread will not take any extra memory. Within the calling code any access to the weak reference will be null in the case that the list was released.

For further information on weak reference please see: http://weblogs.java.net/blog/2006/05/04/understanding-weak-references

Saturday, March 2, 2013

Dilbert's "Salary Theorem"

Spring (3.1) Profiles

We all find ourselves finding solutions to the problem of loading different configurations depending on the environment.
The basic ones are which database to connect to depending if we are in production or testing.

The options are very large, and the solutions many.

Spring now has the option to add an attribute to each bean with a profile, and then you load the context depending on the profile. This will allow you by one flag to define which beans will be loaded when.

For more information see this nice blog:

http://diarmuidmoloney.wordpress.com/2012/04/07/spring-environments/