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 asFoo_Type
in ISO 19139, where Foo is the ISO name of a class. - the
PropertyType
subclasses are defined asFoo_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 likeString
. For this reason the return type must be declared asObject
, 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 abstractgetElement()
from this class.
- Since:
- 0.3
- Version:
- 1.0
- See Also:
-
Field Summary
Fields -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Empty constructor for subclasses only.protected
PropertyType
(BoundType value) Builds a wrapper for the given GeoAPI interface.protected
PropertyType
(BoundType value, boolean mayBeNil) Builds aPropertyType
wrapper for the given primitive type wrapper. -
Method Summary
Modifier and TypeMethodDescriptionprotected final boolean
Returnstrue
if aSince2014
subclasses should return a non-null value.final XLink.Actuate
Communicates the desired timing of traversal from the starting resource to the ending resource.final String
A URI reference for some description of the arc role.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
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
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
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, ornull
if none and thecreate
argument isfalse
.(package private) final BoundType
If the metadata is still null, tries to resolve it using UUID, XLink or NilReason information.final void
setActuate
(XLink.Actuate actuate) Sets theactuate
attribute value.final void
setArcRole
(String arcrole) Sets thearcrole
attribute value.final void
Sets thehref
attribute value.final void
setNilReason
(String nilReason) Sets thenilReason
attribute value.final void
Sets therole
attribute value.final void
setShow
(XLink.Show show) Sets theshow
attribute value.final void
Sets thetitle
attribute value.final void
setUUIDREF
(String uuid) Sets theuuidref
attribute value.private static String
Returns the given URI as a string, or returnsnull
if the given argument is null.private static URI
Parses the given URI, or returnsnull
if the given argument is null or empty.Converts an adapter read from an XML stream to the GeoAPI interface which will contains this value.protected abstract ValueType
Creates a new instance of this class wrapping the given metadata.private XLink
xlink
(boolean create) Returns thexlink
, ornull
if none andcreate
isfalse
.
-
Field Details
-
metadata
The wrapped GeoAPI metadata instance, ornull
if the metadata shall not be marshalled. Metadata are not marshalled when replaced byxlink:href
oruuidref
attributes. -
reference
Eithernull
, anObjectReference
or aString
.ObjectReference
defines theuuidref
,xlink:href
,xlink:role
,xlink:arcrole
,xlink:title
,xlink:show
andxlink:actuate
attributes.String
defines thenilReason
attribute.
-
-
Constructor Details
-
PropertyType
protected PropertyType()Empty constructor for subclasses only. -
PropertyType
Builds aPropertyType
wrapper for the given primitive type wrapper. This constructor checks for nil reasons only ifcheck
istrue
.- Parameters:
value
- the primitive type wrapper.mayBeNil
-true
if we should check for nil reasons.
-
PropertyType
Builds a wrapper for the given GeoAPI interface. This constructor checks if the given metadata implements theNilObject
orIdentifiedObject
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
Returns the object reference, ornull
if none and thecreate
argument isfalse
. If thecreate
argument istrue
, then this method will create the object reference when first needed. In the latter case, any previousgco:nilReason
will be overwritten since the object is not nil. -
xlink
Returns thexlink
, ornull
if none andcreate
isfalse
. If thecreate
argument istrue
, then this method will create the XLink when first needed. In the latter case, any previousgco:nilReason
will be overwritten since the object is not nil. -
getNilReason
The reason why a mandatory attribute if left unspecified.- Returns:
- the current value, or
null
if none.
-
setNilReason
Sets thenilReason
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
A URN to an external resources, or to another part of a XML document, or an identifier. Theuuidref
attribute is used to refer to an XML element that has a correspondinguuid
attribute.- Returns:
- the current value, or
null
if none.
-
setUUIDREF
Sets theuuidref
attribute value.- Parameters:
uuid
- the new attribute value.- Throws:
IllegalArgumentException
- if the given UUID cannot be parsed.
-
toString
Returns the given URI as a string, or returnsnull
if the given argument is null. -
toURI
Parses the given URI, or returnsnull
if the given argument is null or empty.- Throws:
URISyntaxException
-
getHRef
A URN to an external resources, or to another part of a XML document, or an identifier. Thexlink:href
attribute allows an XML element to refer to another XML element that has a correspondingid
attribute.- Returns:
- the current value, or
null
if none.
-
setHRef
Sets thehref
attribute value.- Parameters:
href
- the new attribute value.- Throws:
URISyntaxException
- if the given string cannot be parsed as a URI.
-
getRole
A URI reference for some description of the arc role.- Returns:
- the current value, or
null
if none.
-
setRole
Sets therole
attribute value.- Parameters:
role
- the new attribute value.- Throws:
URISyntaxException
- if the given string cannot be parsed as a URI.
-
getArcRole
A URI reference for some description of the arc role.- Returns:
- the current value, or
null
if none.
-
setArcRole
Sets thearcrole
attribute value.- Parameters:
arcrole
- the new attribute value.- Throws:
URISyntaxException
- if the given string cannot be parsed as a URI.
-
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
Sets thetitle
attribute value.- Parameters:
title
- the new attribute value.
-
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
Sets theshow
attribute value.- Parameters:
show
- the new attribute value.
-
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
Sets theactuate
attribute value.- Parameters:
actuate
- the new attribute value.
-
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()Returnstrue
if aSince2014
subclasses should return a non-null value. This is a convenience method forFilterByVersion.CURRENT_METADATA.accept()
.- Returns:
- whether
Since2014
subclasses should return a non-null value.
-
wrap
Creates a new instance of this class wrapping the given metadata. This method is invoked bymarshal(BoundType)
after making sure thatvalue
is not null.- Parameters:
value
- the GeoAPI interface to wrap.- Returns:
- the adapter.
-
marshal
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 classXmlAdapter<ValueType extends PropertyType<ValueType,
BoundType>, BoundType> - Parameters:
value
- the bound type value, here the interface.- Returns:
- the adapter for the given value.
-
unmarshal
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 classXmlAdapter<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
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
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
-