OpenSSRF Developer Tutorial

Use these simple code templates to get started using OpenSSRF right away.
Replace the "value"
parameters with your own configuration.

Introduction

This tutorial provides Java code snippets to build minimally configured and
compliant SSRF data types in software. Many developer conveniences have been
implemented in this software library, including:

Fluent interface

In each respective data type template a cascading series of "fluent-style" setters
is provided to configure all required sub-types and fields.

Automated serial numbers

SSRF-compliant object serial numbers are automatically generated and managed for you.
You may optionally set the serial number organization and record sequence components
if necessary.

In v3.1.0 a set of utilities are introduced to automate SSRF document
assembly, reading, writing and validation. Also, a powerful properties
utility is introduced to apply document-wide configuration profiles.

Developer Notes

SSRF Software Documentation

NEW

See the OpenSSRF Javadoc
section of this portal for detailed class-level software documentation

SSRF Utility

NEW

OpenSSRF v3.1.0 introduces a new utility class "SSRFUtility"
to automate the processes of SSRF document assembly,
validation, writing and reading. Correctly using the SSRF utilities will
ensure a consistent and valid document.

For your convenience many of the SSRFUtility methods have
been integrated into the SSRF data type and
may be executed on the actual SSRF document directly.

Document Assembly and Writing

Shortcut:

Call SSRF.toXML to prepare and export a SSRF XML document.

After building a SSRF document use the
SSRFUtility.assemble
method to apply SSRF properties and to prepare the SSRF document for
export. Then use the SSRFUtility.validate method
to confirm that all required fields are configured and that all configured
fields contain correctly formatted data.

Document Reading

Shortcut:

Call SSRF.fromXML to build a SSRF software instance from an XML document.

After reading an SSRF message from XML into OpenSSRF software use
the SSRFUtility.postLoad method
to prepare the SSRF data object hierarchy for programmatic manipulation.

Document Validation

Shortcut:

Use SSRF.isValid to inspect your SSRF object instance.

Shortcut:

Use SSRF.evaluate to retrieve a list of validation errors.

At any time you can use the SSRFUtility.validate
method to inspect and validate a SSRF data type. The utility validation method
accepts any SSRF data object, not only the root SSRF data type, and
is a convenient tool to incrementally validate SSRF document assembly
component-by-component.

If validation fails and throws an exception use the
SSRFUtility.evaluate method to inspect the SSRF
class hierarchy and retrieve a complete list of all validation errors.
As above, evaluation accepts any SSRF data object.

SSRF Properties

NEW

OpenSSRF v3.1.0 introduces a new utility class "SSRFProperties"
to automate the assignment of SSRF metadata and other common configuration
values.
The SSRF Properties utility and a powerful tool to simplify SSRF document
creation and to ensure the correct metadata profiles are applied to
exported information.

A default SSRF properties configuration is provided that implements
a global Unclassified information configuration (cls=U)
suitable for general (public) distribution.

Setting SSRF Properties

Properties are applied directly to a SSRF data type with the
setProperty method. For example:

SSRF ssrf = new SSRF();
/**
* Set the default SSRF Properties. This sets the global metadata
* classification (CLS) level to "U" (Unclassified).
*/
ssrf.setProperties(SSRFProperties.getDefault());
/**
* Set the default organisation (sic) for all SSRF serial number instances.
* This may be up to four characters.
*/
ssrf.setProperty("TSerial.organisation", "ic");
/**
* Set the default country code for all SSRF serial number instances. This
* must be an enumerated value selected from ListCCY.
*/
ssrf.setProperty("TSerial.country", "CAN");

SSRF properties are applied when the document is assembled and/or validated.

Reference Types

NEW

Access to Referencing data types is deprecated.

Data-type cross-referencing
is managed automatically with the SSRFUtility class.

In all classes having a Reference data type a new, transient field has been added
to enable direct object linkage. This new transient field is not exported via XML.
This package also includes a new SSRFUtility class for automated
document validation, assembly (WRITE) and parsing (READ).
SSRF data objects are now built using directly object assembly and
cross-referencing is implemented via the new utility.
Just set the referenced object elements in the desired data field
and the software will handle all indexing and cross referencing for you.

For example:
The Message data type contains a DatasetRef list type which
may reference any top-level SSRF data type. This has been superceded with a
new Data list field. To build a Message data type simply add
the desired reference objects to the Data list. These will be copied
to their correct location and a set of DatasetRef instances will be created
when the SSRF message is assmbled written. Conversely, the referenced objects are
copied automatically into the Data list field when a SSRF document
is read and parsed. There should never be a need to access the DatasetRef list
directly.

Message (DatasetRef is Deprecated)

A (old) Message data type. The DatasetRef field is deprecated.

Message (New)

A (new) Message data type. Showing a Transmitter record placed in the new
Data field.

The following Reference data types have been deprecated and removed from the software.
Their function is replaced via direct object reference.

ChannelPlanRef

ContactRef

DatasetRef

LoadsetRef

LocationRef

LocationRestriction

MissingRef

RelatedRef

RFSystemRef

RoleRef

Example Code : Build a SSRF Assignment in Java

Following is a (incomplete) example for building, assembling and
validating a SSRF Assignment document.

Location

Location is used to describe a geographical location, polygonal or ellipse area, or a set of
those.

Location location = new Location()
.withName( "value" );

Message

Message describes the receipt and disposition of a group of Datasets in a single transmittal.
The receiving system SHOULD verify the correct datasets were received. If a dataset fails
validation, a separate Administrative dataset SHOULD be returned to the sender informing
them of the error.

Developer note

Message has been rewritten to automatically handle date type cross-referencing.
Place the referenced object elements in the data field.

Message message = new Message()
withData( "value" );

Note

Note (US) is the XML root for all parameters of a Note.

Note note = new Note();

Organisation

Organisation is the XML root for all parameters of an Organisation (service, agency,
manufacturer, etc).

Receiver

Receiver is the root element (dataset) containing the receiver characteristics.

Receiver receiver = new Receiver()
.withGeneric( "value" );

RFSystem

RFSystem describes the association of one or several Transmitters, Receivers and Antennas as
they are assembled to form a system on a platform; it can also include the specific modes which
are allowed or technically possible in this assembly.

RFSystem rfsystem = new RFSystem();

Role

Role is the XML root for all parameters of a Role (position or role representing an
organisational user of the system; also known as Job Account in the USA).

Role role = new Role()
.withContact(new Contact())
.withName( "value" );