OpenSSRF Developer Tutorial

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.

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

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.

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.

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.

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.

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.

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.

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

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:

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 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 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 indicates a single frequency or a range of frequencies.

AsgnFreqBase asgnfreqbase = new AsgnFreqBase()
  .withFreqMin( "value" );

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 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 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 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 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 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 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 (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 is used to describe a geographical location, polygonal or ellipse area, or a set of those.

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

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.

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

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

Note note = new Note();

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 (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 is the root element (dataset) containing the receiver characteristics.

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

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 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 contains station information related to the space service.

Satellite satellite = new Satellite()
  .withLaunchLoc(new Location()
    .withName( "value" ));

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 contains all parameters describing the system and its usage, for which Spectrum Supportability is being requested.

SSRequest ssrequest = new SSRequest()
  .withTitle( "value" );

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 is the root element (dataset) containing the transmitter characteristics.

Transmitter transmitter = new Transmitter()
  .withGeneric( "value" );