JBoss.orgCommunity Documentation
The Scribble architecture is based on OSGi, to provide a means of managing the individual modules, but without causing tight coupling.
Service bundles enable implementations to be specified that implement defined interfaces. Other services can then request access to services that implement a particular interface.
The OSGi service container takes responsibility of managing the services, and providing access to requesting components.
This provides flexibility for Scribble tooling in two respects:
Replaceable The implementation of a particular Scribble interface can easily be replaced. This enables different research or industry groups to replace specific modules, with alternative implementations, while still reusing other modules.
Extensibility Some aspects of the architecture allow for multiple implementations of the same interface. Therefore, using OSGi, enables additional implementations of the same interface to be easily plugged in, without having to define any additional configuration information.
There is a generic logging API within the Scribble framework that can be used for reporting errors, warnings, information or debuging details. This API is org.scribble.common.logging.Journal .
The methods generally take two parameters, a message and a property map. The message is simply a description of the issue being reported. The property map contain specific details about the issue being reported.
For example, when the parser detects a problem, it can report the nature of the problem, and provide the location of the issue in the source file.
To enable errors reported from the Scribble parser and validation modules, in a number of different languages, internationalization should be used.
The following code fragment provides an example of how internationalization can be achieved, using parameterised messages.
logger.error(java.text.MessageUtil.format( java.util.PropertyResourceBundle.getBundle( "org.scribble.protocol.Messages").getString( "_CHOICE_ROLE"), "from"), obj.getProperties());
The main message content is obtained from a
properties file, with the name being supplied
as the parameter to the
getBundle
method. The property file must be placed
the correct package within the
src/main/resources
folder, to
ensure the properties are correctly packaged
by maven.
The messages within the property files can have values that include parameters. Parameters are numbered in sequential order, and defined between curly braces (e.g. {n} where 'n' is the number). For example,
_EXISTING_DECLARATION=Declaration already exists for name {0}This message only has a single parameter.
In the previous code fragment, the MessageUtil.format() method takes the message as the first parameter, and a variable comma separated list of strings as the parameter values to be substituted in the message. So in the code fragment, the value "from" would be substituted in the {0} parameter of the _CHOICE_ROLE message, and then reported to the journal.
The object model representation of a Protocol is defined using classes within the org.scribble.protocol.model package. All model classes are derived from a common ModelObject class, which defines common properties of all components in the model.
Where object model components are contained by another model component, we use a special list implementation called ContainmentList . This implementation maintains a reference to its containing parent model object, making it easier to navigate up the protocol object model hierarchy.
The Protocol Parser is responsible for converting the textual Scribble notation into an object model representation.
package org.scribble.protocol.parser;
...
public interface ProtocolParser {
public org.scribble.protocol.model.ProtocolModel parse(java.io.InputStream is,
org.scribble.common.logging.Journal journal);
}The parser only has a single method, which takes the input stream containing the text based representation of the Scribble protocol, and a Journal for error reporting purposes.
If the Protocol has valid syntax, then a ProtocolModel will be returned representing the protocol in object model form.
The protocol projection component is used to derive a local protocol representation, associated with a nominated role, from a global protocol representation.
The interface for this component is,
package org.scribble.protocol.projection;
...
public interface ProtocolProjector {
public ProtocolModel project(ProtocolModel model, Role role,
Journal journal);
}This method takes the global protocol model, the role to be projected, and a journal for reporting any errors. The result is either a local representation of the protocol model for the specified role, or null if a failure occurred.
The validation manager, when used in a OSGi runtime
environment, will listen for the activation of any
implementations of the
org.scribble.protocol.validation.Validator
interface.
This means that the validation of any model can be
performed using the
org.scribble.protocol.validation.ValidationManager
,
rather than having to obtain instances of
multiple implementations of the
Validator
interface.
When the
ValidatorManager
is used
outside of an OSGi environment, it is necessary for the
validators to be added to the manager by other means.
One of the default validation implementations is org.scribble.protocol.validation.rules.DefaultProtocolComponentValidator . This class is derived from a generic based class that validates supplied protocol models by visiting the component objects within the model, and invoking a specific 'validation rule' based on the type of the model object.
This default implementation is used to provide the basic validation rules for the model components. For example, to ensure that the roles defined within an interaction have been previously declared within the scope containing the interaction.
The Scribble tools provide a mechanism for exporting a Scribble Protocol object model to other representations. This module has the following interface,
package org.scribble.protocol.exporter;
...
public interface ProtocolExporter {
public String getId();
public String getName();
public void export(ProtocolModel model, Journal journal, java.io.OutputStream os);
}Each 'exporter' implementation defines an id and more descriptive. The id can be used to lookup the implementation from the ProtocolExportManager , whereas the name can be used as a descriptive name for display to users.
The export method takes the protocol model to be exported, the journal where to report errors, and the output stream which will be the destination for the exported representation.
The org.scribble.protocol bundle contains a default exporter to convert the Scribble object model representation into a text based representation. The 'id' for this implementation is txt .
The first step is to define the command implementation of the org.scribble.command.Command interface. This can be created in the org.scribble.command Eclipse plugin.
To initialise the command, as part of an OSGi runtime environment, the command implementation can be instantiated in the org.scribble.command plugin's Activator , and then registered with the bundle context.
If the command requires other OSGi services, then these can be established by setting up service listeners for the relevant service interface classes. When OSGi services are registered, then the relationship can be established.
This command mechanism will generally only be used as part of the command line approach, and therefore does not need to be initialised in other ways. However other dependency injection techniques could be used if appropriate.
The only remaining step is to create the scripts
necessary to enable a user to invoke the command.
This can be achieved by copying one of the existing
scripts, in the
distribution/src/main/release
folder (such as
parse.sh
),
and modify the parameter details as necessary.
The first parameter of the Java application, invoked within the script, must be the name of the command. This must match the value returned by the getName() method on the command interface.