Upgrade Guide: Version 1.x to 2.x

In previous versions of DDMSence, you could point to a custom set of ISM Controlled Vocabulary Enumeration files with the "icism.cve.customEnumLocation" custom property or toggle CVEs to suppress errors with "icism.cve.validationAsErrors". Starting with V5 of ISM.XML (the version bundled with DDMS 3.1), these vocabularies were enforced in the schemas themselves. So, being able to change to a custom set of CVE files or suppress errors no longer made sense, because the CVEs would then present conflicting results when compared to the generated schema files, which strictly enforce the vocabularies.

Both runtime configurable properties have now been removed. Support for alternate ISM schemas and CVEs is now handled as a configuration step to your classpath.

How to Upgrade:

The default selection of ISM schemas and CVEs is now based upon the current DDMSVersion and uses bundled Public Release files all of the time. It is now possible to swap out your entire set of ISM schemas and vocabularies by giving your local copy a higher priority in the Java classpath, as discussed in this Power Tip.

In previous versions of DDMSence, the producer hierarchy was flattened to be more object-oriented. Consider this example:

<ddms:creator>
   <ddms:Organization>
      <ddms:name>DISA</ddms:name>
   </ddms:Organization>	
</ddms:creator>

This creator element was modeled in DDMSence 1.x as "An instance of Organization has the role of creator" and the Organization class contained this entire construct. With DDMS 4.0.1, Organizations and Persons can now appear in other roles besides the classic producers (such as an Addressee or RecordKeeper), and the old approach became too fragile to sustain. Producers and entities are now consistent with the schema -- the above construct is modeled as "An instance of Creator contains an instance of Organization".

Specifically, there is a new class for Creator, Contributor, Publisher, and PointOfContact, and the old entities, Organization Person, Service, and Unknown are no longer top-level components.

How to Upgrade:

To update your code, the four entity classes must now be wrapped into a producer role class. As an example, if you previously had code that worked with a "Service that was a creator":

Service service = new Service("creator", names, phones, emails);

You would now deal with a "Creator that contains a Service":

Service service = new Service(names, phones, emails);
Creator creator = new Creator(service, null, securityAttributes);

In places where you passed an Organization, Person, Service, or Unknown into a Resource constructor as a "top-level component", you will now need to pass in the producer role (Contributor, Creator, PointOfContact, or Publisher) instead.

The hierarchy for related resources used to require both a RelatedResources class and a RelatedResource class:

ddms:relatedResources (0-many in a ddms:resource)
   @ddms:relationship
   @ddms:direction
   @<ismOptionalAttributes>
   ddms:relatedResource (1-many)
      @ddms:qualifier
      @ddms:value
      ddms:link (1-many)

In this model, the ddms:relatedResources element defined the relationship and direction, and a collection of ddms:relatedResource elements shared those values. DDMS 4.0.1 has flattened this to one level:

ddms:relatedResource (0-many in a ddms:resource)
   @ddms:qualifier
   @ddms:value
   @ddms:relationship
   @ddms:direction
   @<ismOptionalAttributes>
   ddms:link (1-many)

To support this in DDMSence, the RelatedResources class has been completely removed. The remaining RelatedResource class now contains all of the required information (including the relationship and direction attributes). The element-based constructor for RelatedResource expects a construct that describes a single related resource. For example:

Pre-DDMS 4.0.1:

<ddms:relatedResources ddms:relationship="http://purl.org/dc/terms/references" ddms:direction="outbound" 
   ISM:classification="U" ISM:ownerProducer="USA">
   <ddms:RelatedResource ddms:qualifier="http://purl.org/dc/terms/URI" ddms:value="http://en.wikipedia.org/wiki/Tank">
      <ddms:link [...] />
   </ddms:RelatedResource>
</ddms:relatedResources>

DDMS 4.0.1

<ddms:relatedResource ddms:relationship="http://purl.org/dc/terms/references" ddms:direction="outbound" 
   ddms:qualifier="http://purl.org/dc/terms/URI" ddms:value="http://en.wikipedia.org/wiki/Tank" 
   ISM:classification="U" ISM:ownerProducer="USA">
   <ddms:link [...] />
</ddms:relatedResource>

In earlier versions of DDMS, having multiple resources with the same relationship and direction was allowed:

Pre-DDMS 4.0.1:

<ddms:relatedResources ddms:relationship="http://purl.org/dc/terms/references" ddms:direction="outbound" 
   ISM:classification="U" ISM:ownerProducer="USA">
   <ddms:RelatedResource ddms:qualifier="http://purl.org/dc/terms/URI" ddms:value="http://en.wikipedia.org/wiki/Tank">
      <ddms:link [...] />
   </ddms:RelatedResource>
   <ddms:RelatedResource ddms:qualifier="http://purl.org/dc/terms/URI" ddms:value="http://en.wikipedia.org/wiki/Fish">
      <ddms:link [...] />
   </ddms:RelatedResource>
</ddms:relatedResources>

If the element-based constructor of RelatedResource encounters this case of multiples, it will only process the first related resource and provide a validation warning message that it is skipping the remainder. However, the element-based constructor for the entire Resource has been updated to mediate this case automatically. The result will be 2 RelatedResource instances, each with the same relation and direction attributes.

How to Upgrade:

If your code is working at the Resource level, you don't need to do a thing. The Resource constructors can handle all legal ddms:relatedResources or ddms:relatedResource elements in all supported DDMS versions. However, if you were instantiating RelatedResources or RelatedResource classes directly via the data-driven constructors, you will need to update your code to stop using the removed class.

If you had old code that looked like this:

List<RelatedResource> list = new ArrayList<RelatedResource>();
list.add(new RelatedResource(links, "qualifier", "resource1"));
list.add(new RelatedResource(links, "qualifier", "resource2"));
RelatedResources resources = new RelatedResources(list, "http://purl.org/dc/terms/references",
   "outbound", securityAttributes);
myTopLevelComponents.add(resources);

The RelatedResources wrapper is now removed:

myTopLevelComponents.add(new RelatedResource(links, "http://purl.org/dc/terms/references", "outbound", "qualifier",
   "resource1"));
myTopLevelComponents.add(new RelatedResource(links, "http://purl.org/dc/terms/references", "outbound", "qualifier",
   "resource2"));

DDMS metacards loaded from an XML file have always been validated against the DDMS schemas. However, DDMS metacards built from scratch (either with the data-driven constructors or the Component Builder framework) were not. Starting in this release, a metacard built from scratch is converted into XML and validated against the schemas, to elminate any remaining loopholes in data correctness. Individual components which are built from scratch are not validated against the schema until the enclosing Resource is instantiated.

How to Upgrade:

There are no upgrade steps required. However, DDMSence v2.0.0 may catch a few additional fringe cases which were mistakenly identified as valid in previous versions. For example, the gml:id on GML points is supposed to be unique to the XML metacard. By using data-driven constructors in the past, it was possible to create multiple points with the same ID value, which would result in an invalid XML record.

DDMS 4.0 was released in September 2011 with an oversight on the technical implementation of the pocType attribute on producer roles. DDMS 4.0 contained a ddms:POCType attribute for this, but it was soon determined by the IC that this would break IRM instances. DDMS 4.0.1 was quickly released a month later and employs ISM:pocType instead.

Although this change (removing the old attribute and adding a new one) breaks backwards compatibility, the decision was made to reuse the DDMS 4.0 XML namespace, given that the adoption of DDMS 4.0 was assumed to be relatively low. Because DDMS 4.0 is considered to be "broken", and because DDMS 4.0.1 was released before I released DDMSence 2.0.0, I have elected not to support DDMS 4.0.

How to Upgrade:

There are no upgrade steps required. "4.0" is not a valid supported DDMS version in DDMSence. If your organization is upgrading from an earlier version of DDMS, the DDMS team is strongly encouraging that you go directly to 4.0.1 anyhow.

Previously, DDMSence would do a basic check to see that security classifications of top-level components were never more restrictive than the metacard itself, and also checked to see that all classifications used a consistent system (US vs NATO). In DDMS 4.0.1, classification markings can go much deeper into the object hierarchy, and NATO markings are now handled apart from classifications. Rather than reinvent the wheel here, it would be better to use the ISM Schematron files to correctly and comprehensively manage your security classifications.

How to Upgrade:

Validate rollup with the Schematron files that come with each version of ISM. There are instructions in the Power Tip on Schematron Validation which show how to use these files with DDMSence.

Person, Organization, Service, Unknown, and CountryCode previously maintained a reference to the enclosing component (such as "creator" for Person or "geographicIdentifier" for CountryCode). This made the hierarchy more fragile than necessary, and has been removed.

How to Upgrade:

Constructor calls which previously had the parentType:

new CountryCode("postalAddress", element);

Now no longer have a parentType:

new CountryCode(element);

Several methods have had their names changed for consistency, or have a different number of parameters.

• Category: The constructor has additional parameters for optional attributes. (Issue #155)
• Dates: The constructor has additional parameters for optional dates. (Issue #117)
• DDMSVersion: getIcismNamespace() became getIsmNamespace() (Issue #95).
• GeographicIdentifier: The constructor has an additional parameter for optional subDivisionCode. (Issue #122)
• ISMVocabulary: setIsmVersion() became setDDMSVersion() (Issue #95).
• Keyword: The constructor has an additional parameter for optional attributes. (Issue #156)
• Organization: The constructor has additional parameters for optional subOrganization and acronym. (Issue #113)
• Person: The order of the constructor parameters has been reordered to match the DDMS 4.0.1 schema (Issue #114)
• RelatedResource: The constructor has additional parameters for new attributes. (Issue #130)
• Resource: getSubjectCoverage() became getSubjectCoverages() and now returns a list of SubjectCoverage components (Issue #126)
• Resource: getDESVersion() became getIsmDESVersion() to avoid conflict with ntk:DESVersion (Issue #131)
• Resource: Constructor updated to include ISM:compliesWith, which used to be part of SecurityAttributes (Issue #168)
• Security: The constructor has additional parametesr for access and noticeList. (Issue #111)
• SubjectCoverage: The constructor has additional parameters for productionMetrics and nonStateActors. (Issue #126)
• Type: The constructor has an additional parameter for optional description. (Issue #118)

How to Upgrade:

If any method calls show compiler errors after upgrading to DDMSence 2.0.0, consult the API documentation and update the method signature. If a constructor has additional parameters to support new data from DDMS 4.0.1 and you are using an older version of DDMS, you can probably get away with simply passing in a null value.

The XLink attributes which decorate a ddms:link element (and other new DDMS 4.0.1 elements) have been extracted into a standalone attribute group called XLinkAttributes.

How to Upgrade:

If you had old Link code that looked like this:

Link link = new Link(href, role, title, label);
String role = link.getRole();

The XLink attributes would now be grouped together:

XLinkAttributes attributes = new XLinkAttributes(href, role, title, label);
Link link = new Link(attributes);
String role = link.getXLinkAttributes().getRole();

Previously, all components had a public NAME field containing the expected name of the component. Because many elements have had their names changed in DDMS 4.0.1 (i.e. ddms:Person became ddms:person), component classes now have a static method which returns a name for some DDMSVersion.

How to Upgrade:

If you had old Link code that looked like this:

String extentName = Extent.NAME;

You would now call a static method:

String extentName = Extent.getName(ddmsVersion);

The non-static getName() method on each component will still return the currently defined name for the component.

Classes are now organized into packages based first on the "Set" from the DDMS specification (Metacard, Resource, Format, etc.) and then on the XML namespace (ISM, GML, etc.).

• Abstract classes have moved up to buri.ddmsence.
• GML classes (Point, Polygon, Position, and SRSAttributes) have moved into buri.ddmsence.ddms.summary.gml.
• ISM classes (ISMVocabulary, and SecurityAttributes) have moved into buri.ddmsence.ddms.security.ism.

How to Upgrade:

Update any Java import statements that point to the old packages.

• icism.prefix became ism.prefix.

How to Upgrade:

Update property names if you used these custom properties.

• MediaExtent renamed to Extent: Because the Media wrapper was removed in DDMS 4.0.1, the old name no longer made sense. (Issue #127).
• IProducerEntity renamed to IRoleEntity: Because Entities can now fulfill non-producer roles, the old name no longer made sense (Issue #163).

How to Upgrade:

Change the class names of the affected classes.