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.
-
Automated indexing
Data element indexed cross referencing via the idx
field
is managed automatically for you.
-
Processing utilities
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.
The SSRFUtilitypostLoad
method copies all referenced data types into their
respective transient positions, greatly simplifying data reading, writing and
reconfiguration.
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)
Message (New)
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.
Source data for this example is a Canadian broadcast television
station record from the
Key Bridge Industry Canada BDBS API
and web service.
SSRF ssrf = new SSRF()
.withAssignment(new Assignment()
.withEntryDateTime(canadaStation.getStCreat())
.withLastChangeDateTime(canadaStation.getStMod())
.withEffectiveDateTime(canadaStation.getStCreat())
.withAssignmentAuthority(ListCHN.USER_ASSIGNED)
.withDataSource(ListUDA.INDUSTRY_CANADA)
.withFCCFileNum(String.valueOf(canadaStation.getDocFile()))
.withOriginalAssignmentDate(canadaStation.getStCreat())
.withUsageType(ListCUT.APPROVED_PERMANENT)
.withTypeOfService(ListUTY.BROADCAST)
.withCaseNum(new CaseNum()
.withCountry(TERRITORY)
.withType("callsign")
.withIdentifier(canadaStation.getCanadaStationPK().getCallSign()))
.withSupplementaryDetails(canadaStation.getNetwork())
.withLastChangeDateTime(canadaStation.getStMod())
.withLastChangeDateTime(canadaStation.getStMod())
.withConfiguration(configuration(canadaStation))
.withStation(station(canadaStation))
.withLink(link(canadaStation)));
A complete SSRF build and translate example application is available
for review and download at the following links:
Example Code Templates (in Java)
SSRF
SSRF (extends SchemaRoot) is the root element for any SSRF-XML message.
It contains attributes defining the
namespace used. Any SSRF-XML message may contain any number of datasets.
SSRF ssrf = new SSRF();
Add any number the following types using their respective "with"
builder
or conventional object set
methods.
Administrative
Data element Administrative has several usages:
- It can be used to inform other data repositories that datasets have been deleted from a data repository;
- It can also be used to reject an incoming dataset which cannot be validated against the local repository, for
example if it refers to unknown datasets.
- Automated local data repository changes are not
permitted on US systems.
Administrative administrative = new Administrative()
.withMessage(new Message())
.withAction( "value" );
Allotment

Allotment is a group of frequencies given to a subordinate organisation for local management,
for specific types of emissions, at a certain location, and for a specified period of time.
Allotment allotment = new Allotment()
.withLocation(new Location()
.withName( "value" ))
.withAllotFreq(new AllotFreq()
.withFreqMin( "value" )
.withLocationRestriction(new Location()
.withName( "value" )))
.withEffectiveDate( "value" );
Antenna

Antenna is the XML root for all parameters of an Antenna. It also contains various technical
parameters of the antenna.
Antenna antenna = new Antenna()
.withAntType( "value" )
.withGeneric( "value" );
AsgnFreqBase

AsgnFreqBase indicates a single frequency or a range of frequencies.
AsgnFreqBase asgnfreqbase = new AsgnFreqBase()
.withFreqMin( "value" );
Assignment

Assignment is the XML root for all parameters of a system of assignments.
Assignment assignment = new Assignment()
.withEffectiveDateTime( "value" )
.withLink(new Link()
.withStationConfig(new StationConfig()
.withStationID( "value" )
.withType( "value" )
.withConfigID( "value" ))
.withLinkID( "value" ))
.withConfiguration(new Configuration()
.withLoadset(new Loadset()
.withName( "value" )
.withJammingChannelProfile(new JammingChannelProfile()
.withCarrierWaveform( "value" )
.withSignal( "value" )
.withFreqMin( "value" )))
.withConfigID( "value" ))
.withStation(new Station()
.withStationLoc(new StationLoc())
.withStationID( "value" ));
ChannelPlan

ChannelPlan describes the plan for the channel set.
ChannelPlan channelplan = new ChannelPlan()
.withChannel(new Channel()
.withChannelFreq(new ChannelFreq()))
.withName( "value" );

Contact is the XML root for all parameters of a Contact.
Contact contact = new Contact();
ExternalReference

ExternalReference contains bibliographic or any other references applicable to the dataset
except those placed in Derivative Classification Authority (Data element ClsDerived).
ExternalReference externalreference = new ExternalReference()
.withIsAttached( "value" );
FEDeployment

FEDeployment describes the deployment of a force element to a location. Each deployment has a
period of time for which the deployment is valid described by the start and end date/time.
FEDeployment fedeployment = new FEDeployment()
.withForceElement(new ForceElement()
.withOwningOrganisation(new Organisation()
.withRole(new Role()
.withContact(new Contact())
.withName( "value" )))
.withNomenclature(new Nomenclature()
.withName( "value" ))
.withType( "value" ))
.withType( "value" );
ForceElement

ForceElement is used to describe any Unit or Platform that has the ability to transmit or
receive RF signals.
ForceElement forceelement = new ForceElement()
.withOwningOrganisation(new Organisation()
.withRole(new Role()
.withContact(new Contact())
.withName( "value" )))
.withNomenclature(new Nomenclature()
.withName( "value" ))
.withType( "value" );
IntfReport

IntfReport contains information on a source and victim of an interference incident.
IntfReport intfreport = new IntfReport()
.withVictimFreqMin( "value" )
.withIntfStartDateTime( "value" )
.withVictimAssignment(new Assignment()
.withEffectiveDateTime( "value" )
.withLink(new Link()
.withStationConfig(new StationConfig()
.withStationID( "value" )
.withType( "value" )
.withConfigID( "value" ))
.withLinkID( "value" ))
.withConfiguration(new Configuration()
.withLoadset(new Loadset()
.withName( "value" )
.withJammingChannelProfile(new JammingChannelProfile()
.withCarrierWaveform( "value" )
.withSignal( "value" )
.withFreqMin( "value" )))
.withConfigID( "value" ))
.withStation(new Station()
.withStationLoc(new StationLoc())
.withStationID( "value" )));
JRFL

JRFL is the XML root for all parameters of a JRFL. It inherits attributes and sub-elements from
element Common.
JRFL jrfl = new JRFL()
.withJrflEntry(new JRFLEntry()
.withJustification( "value" )
.withProtectionCode( "value" ));
Loadset

LoadSet (US) describes the general system setup to be used under a specified set of conditions,
typically related to jamming or frequency hopping.
Loadset loadset = new Loadset()
.withName( "value" )
.withJammingChannelProfile(new JammingChannelProfile()
.withCarrierWaveform( "value" )
.withSignal( "value" )
.withFreqMin( "value" ));
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).
Organisation organisation = new Organisation()
.withRole(new Role()
.withContact(new Contact())
.withName( "value" );
RadiationPlan

RadiationPlan (US) is used to describe the high level plans that can be directed at a specific
target or the mission plan for a group of targets.
RadiationPlan radiationplan = new RadiationPlan()
.withLocation(new Location()
.withName( "value" ))
.withFreqMin( "value" );
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" );
Satellite

Satellite contains station information related to the space service.
Satellite satellite = new Satellite()
.withLaunchLoc(new Location()
.withName( "value" ));
SSReply

SSReply is the XML root for all parameters of a Host Nation Declaration of Spectrum
Supportability. It inherits attributes and sub-elements from element Common.
SSReply ssreply = new SSReply()
.withSupportabilityCode( "value" )
.withSsRequest(new SSRequest()
.withTitle( "value" ))
.withReplyingCountry( "value" )
.withEffectiveDate( "value" );
SSRequest

SSRequest contains all parameters describing the system and its usage, for which Spectrum
Supportability is being requested.
SSRequest ssrequest = new SSRequest()
.withTitle( "value" );
TOA

TOA is the XML root for all parameters of a Table of Allocations. It inherits attributes and
sub-elements from element Common.
TOA toa = new TOA()
.withAdministration( "value" )
.withChannelPlan(new ChannelPlan()
.withChannel(new Channel()
.withChannelFreq(new ChannelFreq()))
.withName( "value" ))
.withFreqBand(new FreqBand()
.withFreqMin( "value" )
.withFreqMax( "value" ));
Transmitter

Transmitter is the root element (dataset) containing the transmitter characteristics.
Transmitter transmitter = new Transmitter()
.withGeneric( "value" );