data.web.upgrade-2.0.0.jsp Maven / Gradle / Ivy
Show all versions of ddmsence Show documentation
DDMSence: Upgrade Guide: Version 1.x to 2.x
<%@ include file="../shared/header.jspf" %>
Upgrade Guide: Version 1.x to 2.x
In order to cleanly and comprehensively support DDMS 4.0.1, DDMSence 2.0.0 required multiple changes which
might break backwards compatibility with your existing code. Some of these changes are as simple as new package names
or changed method names, while others are more significant. This Upgrade Guide describes the changes and provides recommendations on how to migrate your code to use the new version
of DDMSence. If you have followed the instructions in this guide and are still encountering compiler errors or other
problems, I would be glad to assist you further.
- Major Changes
- Minor Changes
Major Changes
Swappable CVE feature expanded (Issue #95, Issue #169, and Issue #154)
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.
Producer/Entity hierarchy changed (Issue #153)
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.
Related Resources hierarchy compressed (Issue #130)
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"));
Non-XML Resources validated against DDMS schemas (Issue #28)
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 skipped in favor of DDMS 4.0.1 (Issue #174)
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.
Minor Changes
Validation for security rollup removed (Issue #165)
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.
Reusable components no longer track parentType (Issue #162)
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);
Method signatures have changed (multiple issues)
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.
XLink attributes encapsulated in a class (Issue #166)
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();
Public NAME constants removed (Issue #152)
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.
Non-DDMS classes moved into new packages (Issue #148)
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.
Configurable property name changed (Issue #95)
icism.prefix became ism.prefix.
How to Upgrade:
Update property names if you used these custom properties.
Class names changed (multiple issues)
- 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.
<%@ include file="../shared/footer.jspf" %>