Package org.apache.sis.internal.jaxb.gco

Class PropertyType<ValueType extends PropertyType<ValueType,BoundType>,BoundType>

java.lang.Object
javax.xml.bind.annotation.adapters.XmlAdapter<ValueType,BoundType>
org.apache.sis.internal.jaxb.gco.PropertyType<ValueType,BoundType>
Type Parameters:
ValueType - the adapter subclass.
BoundType - the interface being adapted.
Direct Known Subclasses:
CC_Conversion, CC_CoordinateOperation, CC_GeneralOperationParameter, CC_GeneralParameterValue, CC_OperationMethod, CC_OperationParameter, CC_OperationParameterGroup, CD_Ellipsoid, CD_EngineeringDatum, CD_GeodeticDatum, CD_ImageDatum, CD_ParametricDatum, CD_PrimeMeridian, CD_TemporalDatum, CD_VerticalDatum, CI_Address, CI_Citation, CI_Contact, CI_Date, CI_OnlineResource, CI_Party, CI_Responsibility, CI_ResponsibleParty, CI_Series, CI_Telephone, CS_AffineCS, CS_CartesianCS, CS_CoordinateSystem, CS_CoordinateSystemAxis, CS_CylindricalCS, CS_EllipsoidalCS, CS_LinearCS, CS_ParametricCS, CS_PolarCS, CS_SphericalCS, CS_TimeCS, CS_UserDefinedCS, CS_VerticalCS, DQ_DataQuality, DQ_Element, DQ_EvaluationMethod, DQ_MeasureReference, DQ_PositionalAccuracy, DQ_Result, DQ_StandaloneQualityReportInformation, DQM_BasicMeasure, DQM_Description, DQM_Measure, DQM_Parameter, DQM_SourceReference, EX_Extent, EX_GeographicExtent, EX_TemporalExtent, EX_VerticalExtent, GO_Boolean, GO_Decimal, GO_Integer, GO_Integer64, GO_MultiplicityRange, GO_Real, GO_Record, GO_RecordType, GO_UnlimitedInteger, LE_Algorithm, LE_NominalResolution, LE_Processing, LE_ProcessStepReport, LI_Lineage, LI_ProcessStep, LI_Source, MD_AggregateInformation, MD_ApplicationSchemaInformation, MD_AttributeGroup, MD_BrowseGraphic, MD_Constraints, MD_ContentInformation, MD_DataIdentification, MD_DigitalTransferOptions, MD_Dimension, MD_Distribution, MD_Distributor, MD_ExtendedElementInformation, MD_FeatureTypeInfo, MD_Format, MD_GeometricObjects, MD_Identification, MD_Identifier, MD_KeywordClass, MD_Keywords, MD_MaintenanceInformation, MD_Medium, MD_Metadata, MD_MetadataExtensionInformation, MD_MetadataScope, MD_PortrayalCatalogueReference, MD_RangeDimension, MD_Releasability, MD_RepresentativeFraction, MD_Resolution, MD_Scope, MD_ScopeDescription, MD_SpatialRepresentation, MD_StandardOrderProcess, MD_Usage, MI_AcquisitionInformation, MI_EnvironmentalRecord, MI_Event, MI_GCP, MI_GeolocationInformation, MI_Instrument, MI_Objective, MI_Operation, MI_Plan, MI_Platform, MI_PlatformPass, MI_RangeElementDescription, MI_RequestedDate, MI_Requirement, MX_DataFile, RS_ReferenceSystem, SC_CRS, SC_GeographicCRS, SC_SingleCRS, SC_VerticalCRS, SV_CoupledResource, SV_OperationChainMetadata, SV_OperationMetadata, SV_Parameter, TM_Duration, TM_PeriodDuration, TM_Primitive
public abstract class PropertyType<ValueType extends PropertyType<ValueType,BoundType>,BoundType> extends XmlAdapter<ValueType,BoundType>
Base class for adapters from GeoAPI interfaces to their SIS implementations. Implementation subclasses are actually both JAXB adapters and wrappers around the value to be marshalled. Wrappers exist because ISO 19139 have the strange habit to wrap every properties in an extra level, for example: The <CI_Contact> level is not really necessary, and JAXB is not designed for inserting such level since it is not the usual way to write XML. In order to get this output with JAXB, we have to wrap metadata object in an additional object. So each PropertyType subclass is both a JAXB adapter and a wrapper. We have merged those functionalities in order to avoid doubling the amount of classes, which is already large.

In ISO 19139 terminology:

  • the public classes defined in the org.apache.sis.metadata.iso packages are defined as Foo_Type in ISO 19139, where Foo is the ISO name of a class.
  • the PropertyType subclasses are defined as Foo_PropertyType in ISO 19139 schemas.

Guidlines for subclasses

Subclasses shall provide a method returning the SIS implementation class for the metadata value. This method will be systematically called at marshalling time by JAXB. Typical implementation (BoundType and ValueType need to be replaced by the concrete class): The actual implementation may be slightly more complicated than the above if there is various subclasses to check.
Note: A previous version provided an abstract getElement() method in this class for enforcing its definition in subclasses. But this has been removed for two reasons:
  • While the return value is usually BoundType, in some situations it is rather another type like String. For this reason the return type must be declared as Object, and subclasses have to restrict it to a more specific type.
  • The parameterized return type forces the compiler to generate bridge methods under the hood. In the particular case of typical PropertyType subclasses, this increases the size of .class files by approximately 4.5%. While quite small, this is a useless overhead since we never need to invoke the abstract getElement() from this class.
Since:
0.3
Version:
1.0
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected BoundType
    metadata
    The wrapped GeoAPI metadata instance, or null if the metadata shall not be marshalled.
    private Object
    reference
    Either null, an ObjectReference or a String.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    PropertyType()
    Empty constructor for subclasses only.
    protected
    PropertyType(BoundType value)
    Builds a wrapper for the given GeoAPI interface.
    protected
    PropertyType(BoundType value, boolean mayBeNil)
    Builds a PropertyType wrapper for the given primitive type wrapper.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final boolean
    accept2014()
    Returns true if a Since2014 subclasses should return a non-null value.
    final XLink.Actuate
    getActuate()
    Communicates the desired timing of traversal from the starting resource to the ending resource.
    final String
    getArcRole()
    A URI reference for some description of the arc role.
    protected abstract Class<BoundType>
    getBoundType()
    Returns the bound type, which is typically the GeoAPI interface.
    final String
    getHRef()
    A URN to an external resources, or to another part of a XML document, or an identifier.
    final String
    getNilReason()
    The reason why a mandatory attribute if left unspecified.
    final String
    getRole()
    A URI reference for some description of the arc role.
    final XLink.Show
    getShow()
    Communicates the desired presentation of the ending resource on traversal from the starting resource.
    final String
    getTitle()
    Just as with resources, this is simply a human-readable string with a short description for the arc.
    final String
    getUUIDREF()
    A URN to an external resources, or to another part of a XML document, or an identifier.
    protected final void
    incomplete(String missing)
    Invoked by subclasses when the unmarshalled object is missing a component.
    final ValueType
    marshal(BoundType value)
    Converts a GeoAPI interface to the appropriate adapter for the way it will be marshalled into an XML file or stream.
    private ObjectReference
    reference(boolean create)
    Returns the object reference, or null if none and the create argument is false.
    (package private) final BoundType
    resolve(Context context)
    If the metadata is still null, tries to resolve it using UUID, XLink or NilReason information.
    final void
    setActuate(XLink.Actuate actuate)
    Sets the actuate attribute value.
    final void
    setArcRole(String arcrole)
    Sets the arcrole attribute value.
    final void
    setHRef(String href)
    Sets the href attribute value.
    final void
    setNilReason(String nilReason)
    Sets the nilReason attribute value.
    final void
    setRole(String role)
    Sets the role attribute value.
    final void
    setShow(XLink.Show show)
    Sets the show attribute value.
    final void
    setTitle(String title)
    Sets the title attribute value.
    final void
    setUUIDREF(String uuid)
    Sets the uuidref attribute value.
    private static String
    toString(Object text)
    Returns the given URI as a string, or returns null if the given argument is null.
    private static URI
    toURI(String uri)
    Parses the given URI, or returns null if the given argument is null or empty.
    BoundType
    unmarshal(ValueType value)
    Converts an adapter read from an XML stream to the GeoAPI interface which will contains this value.
    protected abstract ValueType
    wrap(BoundType value)
    Creates a new instance of this class wrapping the given metadata.
    private XLink
    xlink(boolean create)
    Returns the xlink, or null if none and create is false.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • metadata

      protected BoundType metadata
      The wrapped GeoAPI metadata instance, or null if the metadata shall not be marshalled. Metadata are not marshalled when replaced by xlink:href or uuidref attributes.

    • reference

      private Object reference
      Either null, an ObjectReference or a String.
      • ObjectReference defines the uuidref, xlink:href, xlink:role, xlink:arcrole, xlink:title, xlink:show and xlink:actuate attributes.
      • String defines the nilReason attribute.
      Those two properties are exclusive (if the user defines an object reference, then the attribute is not nil).

  • Constructor Details

    • PropertyType

      protected PropertyType()
      Empty constructor for subclasses only.

    • PropertyType

      protected PropertyType(BoundType value, boolean mayBeNil)
      Builds a PropertyType wrapper for the given primitive type wrapper. This constructor checks for nil reasons only if check is true.
      Parameters:
      value - the primitive type wrapper.
      mayBeNil - true if we should check for nil reasons.

    • PropertyType

      protected PropertyType(BoundType value)
      Builds a wrapper for the given GeoAPI interface. This constructor checks if the given metadata implements the NilObject or IdentifiedObject interface. If the object implements both of them (should not happen, but we never know), then the identifiers will have precedence.
      Parameters:
      value - the interface to wrap.

  • Method Details

    • reference

      private ObjectReference reference(boolean create)
      Returns the object reference, or null if none and the create argument is false. If the create argument is true, then this method will create the object reference when first needed. In the latter case, any previous gco:nilReason will be overwritten since the object is not nil.

    • xlink

      private XLink xlink(boolean create)
      Returns the xlink, or null if none and create is false. If the create argument is true, then this method will create the XLink when first needed. In the latter case, any previous gco:nilReason will be overwritten since the object is not nil.

    • getNilReason

      public final String getNilReason()
      The reason why a mandatory attribute if left unspecified.
      Returns:
      the current value, or null if none.

    • setNilReason

      public final void setNilReason(String nilReason)
      Sets the nilReason attribute value. This method does nothing if a non-null reference exists, since in such case the object can not be nil.
      Parameters:
      nilReason - the new attribute value.

    • getUUIDREF

      public final String getUUIDREF()
      A URN to an external resources, or to another part of a XML document, or an identifier. The uuidref attribute is used to refer to an XML element that has a corresponding uuid attribute.
      Returns:
      the current value, or null if none.

    • setUUIDREF

      public final void setUUIDREF(String uuid) throws IllegalArgumentException
      Sets the uuidref attribute value.
      Parameters:
      uuid - the new attribute value.
      Throws:
      IllegalArgumentException - if the given UUID cannot be parsed.

    • toString

      private static String toString(Object text)
      Returns the given URI as a string, or returns null if the given argument is null.

    • toURI

      private static URI toURI(String uri) throws URISyntaxException
      Parses the given URI, or returns null if the given argument is null or empty.
      Throws:
      URISyntaxException

    • getHRef

      public final String getHRef()
      A URN to an external resources, or to another part of a XML document, or an identifier. The xlink:href attribute allows an XML element to refer to another XML element that has a corresponding id attribute.
      Returns:
      the current value, or null if none.

    • setHRef

      public final void setHRef(String href) throws URISyntaxException
      Sets the href attribute value.
      Parameters:
      href - the new attribute value.
      Throws:
      URISyntaxException - if the given string cannot be parsed as a URI.

    • getRole

      public final String getRole()
      A URI reference for some description of the arc role.
      Returns:
      the current value, or null if none.

    • setRole

      public final void setRole(String role) throws URISyntaxException
      Sets the role attribute value.
      Parameters:
      role - the new attribute value.
      Throws:
      URISyntaxException - if the given string cannot be parsed as a URI.

    • getArcRole

      public final String getArcRole()
      A URI reference for some description of the arc role.
      Returns:
      the current value, or null if none.

    • setArcRole

      public final void setArcRole(String arcrole) throws URISyntaxException
      Sets the arcrole attribute value.
      Parameters:
      arcrole - the new attribute value.
      Throws:
      URISyntaxException - if the given string cannot be parsed as a URI.

    • getTitle

      public final String getTitle()
      Just as with resources, this is simply a human-readable string with a short description for the arc.
      Returns:
      the current value, or null if none.

    • setTitle

      public final void setTitle(String title)
      Sets the title attribute value.
      Parameters:
      title - the new attribute value.

    • getShow

      public final XLink.Show getShow()
      Communicates the desired presentation of the ending resource on traversal from the starting resource. It's value should be treated as follows:
      • new: load ending resource in a new window, frame, pane, or other presentation context
      • replace: load the resource in the same window, frame, pane, or other presentation context
      • embed: load ending resource in place of the presentation of the starting resource
      • other: behavior is unconstrained; examine other markup in the link for hints
      • none: behavior is unconstrained
      Returns:
      the current value, or null if none.

    • setShow

      public final void setShow(XLink.Show show)
      Sets the show attribute value.
      Parameters:
      show - the new attribute value.

    • getActuate

      public final XLink.Actuate getActuate()
      Communicates the desired timing of traversal from the starting resource to the ending resource. It's value should be treated as follows:
      • onLoad: traverse to the ending resource immediately on loading the starting resource
      • onRequest: traverse from the starting resource to the ending resource only on a post-loading event triggered for this purpose
      • other: behavior is unconstrained; examine other markup in link for hints
      • none: behavior is unconstrained
      Returns:
      the current value, or null if none.

    • setActuate

      public final void setActuate(XLink.Actuate actuate)
      Sets the actuate attribute value.
      Parameters:
      actuate - the new attribute value.

    • getBoundType

      protected abstract Class<BoundType> getBoundType()
      Returns the bound type, which is typically the GeoAPI interface. Subclasses need to return a hard-coded value. They shall not compute a value from the object fields, because this method is invoked from the constructor.
      Returns:
      the bound type, which is typically the GeoAPI interface.

    • accept2014

      protected final boolean accept2014()
      Returns true if a Since2014 subclasses should return a non-null value. This is a convenience method for FilterByVersion.CURRENT_METADATA.accept().
      Returns:
      whether Since2014 subclasses should return a non-null value.

    • wrap

      protected abstract ValueType wrap(BoundType value)
      Creates a new instance of this class wrapping the given metadata. This method is invoked by marshal(BoundType) after making sure that value is not null.
      Parameters:
      value - the GeoAPI interface to wrap.
      Returns:
      the adapter.

    • marshal

      public final ValueType marshal(BoundType value)
      Converts a GeoAPI interface to the appropriate adapter for the way it will be marshalled into an XML file or stream. JAXB calls automatically this method at marshalling time.
      Specified by:
      marshal in class XmlAdapter<ValueType extends PropertyType<ValueType,BoundType>,BoundType>
      Parameters:
      value - the bound type value, here the interface.
      Returns:
      the adapter for the given value.

    • unmarshal

      public BoundType unmarshal(ValueType value) throws URISyntaxException
      Converts an adapter read from an XML stream to the GeoAPI interface which will contains this value. JAXB calls automatically this method at unmarshalling time.
      Specified by:
      unmarshal in class XmlAdapter<ValueType extends PropertyType<ValueType,BoundType>,BoundType>
      Parameters:
      value - the adapter for a metadata value.
      Returns:
      an instance of the GeoAPI interface which represents the metadata value.
      Throws:
      URISyntaxException - if a URI cannot be parsed.

    • resolve

      final BoundType resolve(Context context) throws URISyntaxException
      If the metadata is still null, tries to resolve it using UUID, XLink or NilReason information. This method is invoked at unmarshalling time.
      Throws:
      URISyntaxException - if a nil reason is present and cannot be parsed.

    • incomplete

      protected final void incomplete(String missing) throws IllegalArgumentException
      Invoked by subclasses when the unmarshalled object is missing a component. This method is invoked when the missing component is essential to SIS working. This method is not invoked if the missing component is flagged as mandatory by GML, but is not mandatory for SIS working.
      Parameters:
      missing - the name of the missing XML component.
      Throws:
      IllegalArgumentException - always thrown.
      Since:
      0.7