Joint Open Source Interface Framework

Owned by Craig Gallen [Administrator] (Unlicensed)
Last updated: Dec 04, 2012Version comment
7 min read

JOSIF Main Page | Joint Open Source Interface Framework

Introduction

The JOSIF project is intended to provide tooling to help with the consistent specification, documentation and implementation of large scale enterprise SOA architectures. The tooling is being targeted at Enterprises, Vendors, Systems Integrators and Standards Organisations who would benefit from a model driven engineering approach for consistently managing their enterprise data models and integration interfaces. In the context of the TM Forum it is being used to define standard interfaces derived from the SID model. However we have proposed the tooling to other standards organisations including the ITU SG2 in Geneva, 3GPP and ATIS. The tooling has deliberately been made open source to significantly reduce the barriers to entry and to overcome obstacles to adoption by organisations other than the TM Forum and the initial committers.

JOSIF is an open source project hosted as one of the projects on the OpenOSS site on Sourceforge (http://openoss.sourceforge.net/). Presently the committers come from HP, Telcordia, Nortel/Ciena, DT and OpenNMS. The contributed code is all licensed using the Apache 2 licence. Since its inception in 2008, approximately 10 man years of effort have gone into getting the project to this stage. The JOSIF project draws heavily on the Eclipse/Tigerstripe project which is primarily sponsored by Cisco. As far as we know the JOSIF project is the largest user of Tigerstripe outside of Cisco's internal projects. Cisco have about 5 developers working on Tigerstripe and although they have not been directly contributing to JOSIF, they have been very helpful to the team. Cisco developed the initial UML import plugin which we use to import SID objects from RSM.

Interface Modelling and Specification Support

The JOSIF project has developed code and documentation generators (plugins) for Tigerstripe and a complete build system which can allow multiple teams to develop separate interfaces derived from a version controlled set of common Tigerstripe models. The build system is based upon Maven and stores releases and snapshots of Tigerstripe Models, Plugins and Profiles in a Maven repository on the internet. Maven is also used to distribute the generated artefacts (models, Java code, WSDL and documentation) as dependencies for downstream projects. A Project Creator is provided to help developers to rapidly create working JOSIF projects which download and use the correct artefacts. A developer who has already installed Maven and Tigerstripe should be able to create a working project in about 15 minutes.

The TM Forum are currently specifying each interface using XML. Thus the generated XML is normative and supports a WSDL Contract-first style of programming. The JOSIF Soap plug-in generates WSDL interfaces according to the Soap 1.1 specification. The rules governing how the Tigerstripe models are mapped to WSDL are documented here on the TIP Soap Generator page

The build system for each interface specification project pulls in the required dependencies (Models and /or pre-generated XML) and combines these with the output from the interface model. The generated WSDL is tested for usability using a common wsdl2java generator ( Apache CXF ) before being packaged with the Tigerstripe generated documentation and any other documentation into a single packaged specification zip file.

JOSIF also provides a plug-in for importing UML models from Rational RSM. This is primarily used to import SID artefacts for interface standardisation. The JOSIF project has also begun work on a plug-in for testing model correctness. This applies rules to discover potential problems in an imported model before it is used in the build process. The plug-in currently only supports 5 rules but it has already discovered hundreds of examples of inconsistencies in the SID. Although we have not set up a continuous build system, the project is designed to support a continuous build such that changes checked into the model can automatically trigger a build which would test the artefacts before they are used down-stream.

Java Specification Support

Although not yet subject to a rigorous specification process, a generator is also provided to generate a Java Specification (API). The generated Javadoc includes documentation derived from the model. It is hoped that the Java API will eventually be suitable for adoption as a Java profile of the interfaces presently standardised in WSDL. This could be positioned as a next generation of OSS/J through the JCP. However no decisions have been made about how to formalise this work. The present primary intention of this work is to provide the basis for creating RI's (Reference Implementations) and CTK's (Compatibility Test Kits) in support of the standards. The Java Specification Generator generates code which is heavily influenced by the design patterns in OSS/J. Like OSS/J the interface specification supports

  • An attribute access mechanism based upon attribute name constants
  • Methods to find all supported operations (Note that this finds all supported operations and not just the supported optional operations as in OSS/J)
  • Methods to find all populated attributes
  • Factory methods to return implementation classes

The principle differences from the OSS/J design patterns are

  • Moving from Java 1.4 to use Java 1.5 features where appropriate including Generics and Annotations
  • Moving to EJB 3
  • Using a message template based input / output pattern for generated methods which more closely matches the pattern used in the WSDL interface.

Java Implementation Code Generation

JOSIF provides Tigerstripe Generators to create Implementation and Test code which can be used as a basis for the RI's and CTK's - or perhaps more importantly can be used as a starting point for developers implementing a working interface. Note that an implementation project can also be used to extend a standardised interface's model to include proprietary extensions for a vendor's implementation.
Two primary philosophies have guided the code generation project. Firstly the project has sought to build on the strengths of OSS/J and as far as possible to use Java standards and widely adopted open source libraries. Secondly, the project has striven to build enough early functionality in order to 'get it working' and be able to demonstrate the full scope of the solution before seeking to optimise the implementation. This has been very much with a view to attracting other potential adopters or developers who can modify, enhance and complete the basic framework. A key component which supports early adopters and evaluators is the Project Creator which is provided to allow users to rapidly set up working archetype implementation projects which already provide a complete Maven build and test system and Eclipse integration. The following notes provide a description of the code which can be generated by the JOSIF implementation plug-ins.

The generated implementation code uses Spring to provide wiring of objects using dependency injection. The factory methods are backed by Spring XML application contexts. Basic XML application context files are automatically generated which cause the factory methods to return the default implementation classes. However these can be modified as an implementation project proceeds such that the default generated code is gradually replaced by more complete hand-modified implementation code.
The generated code includes a persistence layer using JPA annotations. The generated persistence layer is intended to give a head start for a programmer wishing to write an RI. For more sophisticated interfaces, an implementer may wish to supplement this DAO layer with a Domain Model layer which controls sequential access or dependencies between the basic objects. However for many simple interfaces, the DAO model is quite sufficient. The default generated annotations can be modified using stereotypes applied to the model. This can allow an implementer to map the persistence layer directly onto a pre-existing database. A Generic DAO pattern is used to provide DAO's for each object type. The base Generic DAO is implemented using Hibernate but could be replaced by another JPA based implementation such as Toplink/EclipseLink.

Note that an alternative to directly generating a persistence mechanism would have been to use a tool like Hyperjaxb3, an open source project which provides relational persistence for JAXB objects. This would provide a short-cut for RI developers if they were only interested in the WSDL standard. However it would make it difficult to introduce a domain model later if needed. We are presently working on a marshalling layer which will map the Standardised WSDL onto the OSS/J-like Java API. This means that (as in the OSS/J TCK Framework), the same tests can be written for use against the Java API and against the marshalled WSDL API. Similarly if the Java interface is standardised, an implementer will only have to create the interface behaviour once. The marshalling layer will use JAX-WS and JAXB (Presently using the Apache CXF implementation).

In addition to generating the persistence and marshalling code, we also generate test code using the TestNG framework. This provides much greater flexibility to define groups of tests and dependencies between texts than simple Junit tests. The generated tests provide unit testing of the generated implementation code including tests of persistence, tests of attribute access code and tests of the factory methods. Every business method is provided with a very basic test which can be used as a template for more sophisticated tests of behaviour in a CTK. By default the EJB3 interfaces are tested in an OpenEJB container running in Maven.

Potential uses outside of the TM Forum

As stated above, the framework has been written with the express intention of providing tooling to help with the consistent specification, documentation and implementation of large scale enterprise SOA architectures. The JOSIF tooling would provide a very strong starting point for prototyping the design of an enterprise model and SOA interfaces for any significant customer engagement.

Tigerstripe provides a much simpler paradigm for defining interfaces than most UML tools and more importantly it allows many programmers to share work on the same model. However the Tigerstripe project has not released very sophisticated code generators with the base platform. The JOSIF project has significantly supplemented Tigerstripe with a Maven build system and code generators which are sufficiently generic to be useful for enterprises wishing to create interfaces from their own models. There is no dependency in the tooling on any TM Forum models or artefacts. Any common models used by the tooling are Apache licensed and hosted as part of the JOSIF project.

Being open source, it is also possible for users to fork these generators as a starting point for generating more specific code targeted on their platforms. As an example, the OpenNMS project is presently investigating applying this framework to generate the core model and persistence layer used to represent networks within OpenNMS.