GIT is a relatively new source code management system.

The distinguishing feature of GIT, over other more common SCM systems such as subversion and cvs, is that it works as a network of repositories.

Most, if not all other, SCM technologies use a central repository that all users check code in and out of. GIT makes a local repository on the users box that is then synchronized with the network based repository.

When someone wishes to enhance the project in some way, they can opt to collaborate on that network based repository, or fork the repository and work independently of the main repository. At a suitable point in the future, they can then request that their changes are 'pulled' back into the main project, or simply remain as a separate project.

For the purposes of the Scribble project, this way of working seems ideal. Different groups, whether industry or academic, can take their own forks of the project and make use of them in their own specific ways.

When those groups produce something that they feel is generally useful for the Scribble community, they can request that the main Scribble project 'pulls' the relevant changes to incorporate the new functionality.

However, it also means that those separate groups can build their own specific features that can remain localised to their version of the project.

Although these forked projects would be separate from the main project, they can be configured to be notified when changes are made to the main project, so that they can opt to merge in the new changes. This way, it enables all of the satellite projects to remain up-to-date with changes in the new project.

GIT has been specifically designed to make forking and merging repositories easy.

The project is currently hosted at GIT Hub which provide useful tools around the GIT repository.

Currently issue management is handled by the Scribble project hosted on github.

However each separate (forked) project may maintain its own set of issues, relate to its own functionality. Although hopefully issues that effect the functionality in the core (shared) project should be reported to the main GIT project.

The project build is performed using maven.

The maven plugins, used to build the OSGi bundles, are fairly common. Although specific maven plugins do exist for building OSGi bundles, they don't currently work well.

However, basically all that is required is the ability to package the relevant classes in a jar with a manifest that defines the relevant OSGi properties. Therefore this is what we use.

The other generally used maven plugins relate to compilation of the Java classes, execution and analysis of JUnit tests.

The Scribble tools architecture is based on OSGi, which means that the OSGi compliant bundles can run within any OSGi compliant service container. However OSGi is a service framework, intended to manage services in a service container (or server).

Therefore, to leverage OSGi bundles (or services), from a command line invoked application, we need to select a specific OSGi implementation that supports this approach, as it is not defined as part of the OSGi standard.

Therefore, to provide this command line capability, we have selected the Apache Felix OSGi implementation. This is the reason that the Felix jars are included in the distribution's lib sub-folder, rather than just implementation independent OSGi jars.

Although it is possible to define new modules as part of the Scribble project, it is also possible to develop them independently and just place them within the bundle folder of the installed (unpacked) Scribble distribution. This will make them available as part of the command line commands (e.g. if the bundle represents an additional validation module).

OSGi is about defining components, with well defined interfaces, and managing their isolation, to enable modules to be dyamically added or removed as necessary.

However, it is also possible to use these same components, based on the separate of interfaces and implementations, using any suitable factory or direct injection approach.

The bundles are just normal jar archives. They only have special significants when placed in an OSGi container.

To integrate the Scribble protocol model, parser and supporting validating modules into Eclipse, it is necessary to package them in the form of an update site.

The integration/eclipse/updatesite folder contains the Eclipse artifacts used to build the update site (specifically the site.xml file). When this file is opened within an Eclipse environment, that contains the Plugin Development Environment (PDE), it will open the file in a special editor. The update site can be built by selecting the Build All button.

Once the plugins and features have been built, then the updatesite folder contents should be zipped up, and distributed as necessary. This can be downloaded for use as a local update site, or exploded into a suitable location on the network, to be made available as a remote update site.

The details of which features, and therefore plugins, are included in the update site, are defined in the site.xml file.

As well as incorporating the OSGi bundles defined in the modules sub-folder, the Eclipse integration has some additional Eclipse specific plugins.

For example, the Scribble Designer is included as an additional plugin within the Eclipse integration branch of the project structure.

This part of the project structure provides a set of tests to check that the parser (being tested) processes the supplied set of test 'protocol' descriptions, and returns the correct object model.

The test protocol descriptions are stored in the src/test/resources/tests folder.

Each test is accompanied by a junit test, defined in the class org.scribble.protocol.parser.ctk. For example:

	@org.junit.Test
	public void testSingleInteraction() {
		TestScribbleLogger logger=new TestScribbleLogger();
		
		Model<Protocol> model=getModel("SingleInteraction", logger);
		
		assertNotNull(model);
		
		assertTrue(logger.getErrorCount() == 0);
		
		// Build expected model
		Model<Protocol> expected=new Model<Protocol>();
		
		Namespace ns=new Namespace();
		ns.setName("example.helloworld");
		expected.setNamespace(ns);
		
		Protocol protocol=new Protocol();
		expected.setDefinition(protocol);
		
		LocatedName ln=new LocatedName();
		ln.setName("SingleInteraction");
		protocol.setLocatedName(ln);
		
		ParticipantList rl=new ParticipantList();
		Participant buyer=new Participant();
		buyer.setName("buyer");
		rl.getParticipants().add(buyer);
		Participant seller=new Participant();
		seller.setName("seller");
		rl.getParticipants().add(seller);
		
		protocol.getBlock().getContents().add(rl);
		
		Interaction interaction=new Interaction();
		
		MessageSignature ms=new MessageSignature();
		TypeReference tref=new TypeReference();
		tref.setLocalpart("Order");
		ms.getTypes().add(tref);
		interaction.setMessageSignature(ms);
		interaction.setFromRole(buyer);
		interaction.setToParticipant(seller);
		
		protocol.getBlock().getContents().add(interaction);
		
		verify(model, expected);
	}
			

The getModel() method retrieves the protocol description from a named file, and invokes the parser implementation being tested.

The parser implementation is defined using the scribble.protocol.parser system property. If this property is not set, then it will default to the ANTLR based implementation.

Once the model has been retrieved using the parser, the unit test will construct an 'expected' object model.

The final step in the unit test is to invoke the verify() method to compare the model retrieved against the 'expected' version.

To perform the verification, each model is flattened to produce a list of 'model objects'. Then the verification mechanism iterates through the list, checking that the same entry in each list is identical - first checking they are the same class, and then invoking a 'comparator' implementation for that class.

The 'comparator' implementations are defined in the org.scribble.protocol.parser.ctk.comparators package. The comparator implementations are registered in the static initializer for the org.scribble.protocol.parser.ctk.ProtocolParserTest class.