JBoss.orgCommunity Documentation
This section outlines the technology used to manage the different aspects of the project.
The issue management is handled through the JIRA system located at https://jira.jboss.org/browse/SCRIBBLE .
Issues can be created for bugs, feature requests and tasks. Bugs are used to report unexpected behaviour, and will generally be created by language/tool users. Feature requests can equally be used by users to request new language or tool features.
Tasks will only generally be created by project developers, as a way of keeping track of work that needs to be done, potentially in support of bugs or feature requests.
Issues in JIRA can be linked, where a dependency exists. It is also possible to create a simple hierarchiy with tasks, such that a parent task can contain related sub-tasks.
An important usage of the issue management system is to keep track of what issues are associated released versions of the tools, and what target release they will be implemented or fixed within. This enables users to understand the schedule of features and bug fixes, aswell as providing an automated mechanism for providing release notes describing the work associated with a particular release.
The project build is performed using maven. A specific maven plugin, called Tycho, is used to build the Eclipse based OSGi modules.
The project also uses the Hudson continuous build and integration system to automatically trigger the build when changes are detected in the Scribble subversion repository.
Using the continuous build approach enables problems to be detected at the earliest possible stage. The build includes the execution of JUnit tests, implemented as part of the project, and the reporting of their results.
The distribution mechanism is aimed at providing a zipped archive that contains the necessary environment.
This environment provides the ability to execute Scribble
commands from the command line. However it is also possible
to use the jars, contained in the
lib
and
bundle
sub-folders, directly within
other Java applications.
To automatically include a new bundle in the distribution
(
bundle
subfolder), it should be
defined in the
org.scribble.bundles
maven group.
The build procedure also creates an Eclipse update site that includes the OSGi bundles as well as some additional Eclipse specific plugins (e.g. protocol editor).
The
runtime
branch of the project
is concerned with providing integration of the OSGi
bundles, defined in the
tools/bundles
branch,
in different execution environments.
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 separation of interfaces and implementations, using any suitable factory or direct injection approach.
The bundles are just normal jar archives. They only have special significance 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. This is achieved using the maven plugin called Tycho.
The
tools
folder within the source
project structure contains all of the OSGi and Eclipse
based artifacts.
The
bundles
sub-folder contains the
OSGi modules that can be used in an OSGi container, or
integrated with the Eclipse specific plugins into an
Eclipse update site.
The
features
and
plugins
sub-folders contain the more traditional Eclipse features
and plugins. These plugins provide the Eclipse specific
capabilities that also utilise the capabilities of
the OSGi modules defined in the
bundles
sub-folder.
The
site
sub-folder provides the update
site definition. This is used by Tycho to build an
update site from the specified features, plugins and other
OSGi bundles.
The update site that is built as part of the maven build scripts is not included as part of the distribution. The update site is intended to be installed on a network server, to enable users to reference it from the update manager in their Eclipse environment.
The final sub-folder within the
tools
structure is the tests
sub-folder. This is used to define the test plugins that are invoked as part of the Tycho build mechanism.
The
tools/bundles
sub-folder contains all of the
OSGi compliant bundles that can be used in any of the integration
environments.
Some of the main bundles in this sub-folder are:
org.scribble.common This module provides common capabilities used by the other bundles.
org.scribble.protocol This is the main 'protocol' related module. It contains the protocol object model, and the interfaces for the other main components in the tool chain.
org.scribble.protocol.parser This module provides the ANTLR based parser implementation.
org.scribble.protocol.projection This module provides the endpoint projection mechanism.
org.scribble.protocol.monitor and org.scribble.protocol.export.monitor These modules provide the runtime monitoring support. The export monitor bundle converts a Protocol object model into the concise monitoring finite state machine representation, and the org.scribble.protocol.monitor module provides the Java based monitoring engine implementation.
There are two types of QA that are performed as part of the project:
Local test cases Unit tests would be used to test the individual classes within the specific implementation of an interface.
Integration tests Where multiple implementations of a particular module could exist, an integration test strategy may be useful to ensure that all implementations of the same interface behaviour in the same way. This section will discuss the second type of QA, aimed at ensuring multiple implementations behaviour in the same way.
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.
The
global
sub-folder provides
the global representation of the protocols, with the
local representation of these protocols (for all of the
relevant roles) being defined in the
local
sub-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() {
TestJournal logger=new TestJournal();
ProtocolModel model=CTKUtil.getModel("tests/protocol/global/SingleInteraction.spr", logger);
assertNotNull(model);
assertTrue(logger.getErrorCount() == 0);
// Build expected model
ProtocolModel expected=new ProtocolModel();
ImportList imp=new ImportList();
TypeImport t=new TypeImport();
t.setName("Order");
imp.getTypeImports().add(t);
expected.getImports().add(imp);
Protocol protocol=new Protocol();
expected.setProtocol(protocol);
protocol.setName("SingleInteraction");
RoleList rl=new RoleList();
Role buyer=new Role();
buyer.setName("Buyer");
rl.getRoles().add(buyer);
Role seller=new Role();
seller.setName("Seller");
rl.getRoles().add(seller);
protocol.getBlock().add(rl);
Interaction interaction=new Interaction();
MessageSignature ms=new MessageSignature();
TypeReference tref=new TypeReference();
tref.setName("Order");
ms.getTypeReferences().add(tref);
interaction.setMessageSignature(ms);
interaction.setFromRole(buyer);
interaction.getToRoles().add(seller);
protocol.getBlock().add(interaction);
CTKUtil.verify(model, expected);
}The CTKUtil.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 CTKUtil.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.
As with the parser, the CTK provides a set of tests that can be used to test the projection implementation.
The projector implementation is defined using the scribble.protocol.projector system property. If this property is not set, then it will use the default implementation.
The tests are performed by initially retrieving the global representation of a Protocol, and then the local representation that is associated with the particular role that will be projected. This local representation effectively becomes the 'expected' projection.
The project is then invoked, for the required role, which will produce another local representation. All that is then left to do is verify that the projected local representation is identical to the local representation loaded from the file.
An example of a projection test is shown below, where the global model is being projected to the Buyer role:
@org.junit.Test
public void testSingleInteractionAtBuyer() {
TestJournal logger=new TestJournal();
ProtocolModel model=CTKUtil.getModel("tests/protocol/global/SingleInteraction.spr", logger);
assertNotNull(model);
assertTrue(logger.getErrorCount() == 0);
ProtocolModel expected=CTKUtil.getModel("tests/protocol/local/SingleInteraction@Buyer.spr", logger);
assertNotNull(expected);
assertTrue(logger.getErrorCount() == 0);
// Produce projection of model to buyer
Role role=new Role("Buyer");
ProtocolModel projected=CTKUtil.project(model, role, logger);
CTKUtil.verify(projected, expected);
}
The monitoring CTK tests are based on simulating a set of events
against the local representation of protocols, as defined in the
tests/protocol/local
sub-folder.
The JUnit tests are structured as follows:
@org.junit.Test
public void testSingleInteractionXSDImportAtBuyer() {
testMonitor("tests/protocol/local/SingleInteractionXSDImport@Buyer.spr",
"tests/monitor/SingleInteractionXSDImport@Buyer.events", false);
}They simply specify the location of the local protocol representation that will be monitored, and the location of the file containing the list of events to be simulated. The final parameter indicates whether the test (or simulation) is expected to fail.
The event file has the same structure as used with the simulate command line function. For example,
receiveMessage,Order sendChoice,validProduct sendMessage,Order receiveChoice,_Confirmation receiveMessage,Confirmation sendMessage,Confirmation