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.

  • 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.

Example SSRF Default Properties Default.properties

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 SSRF build utility OpenSSRF_BDBS
Example translator utility: SSRF from IC-BDBS SSRFTranslatorBDBS

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

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" );
Session Error

Your session may have timed out or encountered an error. Please refesh the page to continue.