org.eclipse.higgins.idas.api
Interface IMetadata

public interface IMetadata

TODO (Doc): Add (or point to) doc which explains what metadata is and how it's used

TODO (Doc): Show an example (preferably that of an owner or source for the object to which some metadata is attached) TODO (Doc): Finish javadoc for methods

Method Summary

IComplexMetaValue	addComplexValue(URI dataType) Creates a new complex value for this metadata element.
ISimpleMetaValue	addSimpleValue(URI dataType, Object data) Creates a new simple value for this metadata element.
IMetadataValue	addValue(IMetadataValue copyFrom) Creates a new value for this metadata element by copying the passed IMetadataValue Note: This operation is only applied to any backing data store after IContext.applyUpdates() is called.
IMetadataValue	addValue(URI dataType) Creates a new value for this metadata element.
boolean	equals(IMetadata meta) Returns true if the passed metadata is equal to this one.
URI	getMetaID() Returns the metadata ID of this metadata as a URI.
IMetadataModel	getModel() Returns a model of this type of metadata as it defined in the context's schema.
Iterator	getValues() Returns all values for this metadata element.
boolean	isSingleValued() Convenience method which returns true when the model for this metadata dictates that only a single value may exist.
void	remove() Removes this metadata element from its container Note: This operation is only applied to any backing data store after IContext.applyUpdates() is called.

Method Detail

getMetaID

public URI getMetaID()
              throws IdASException

Returns the metadata ID of this metadata as a URI.

From this URI, a consumer should be able to derive some kind of human-readable identifier (such as "timeToLive", "owner", "creationDate", etc.).

This metadata ID is used to distinguish this metadata from other metadata elements within a collection of metadata. Note that IModel.getType() will return the same URI that this method returns. The reason we use the term "MetaID" here is because from a metadata instance point of view, this is the identifier which distinguishes this metadata element from others. The reason it is referred to as a type from the metadata's model point of view is because it's tied to the capabilities of the metadata.

Throws:

IdASException

getValues

public Iterator getValues()
                   throws IdASException

Returns all values for this metadata element.

Returns:

an Iterator of IMetadataValues

Throws:

IdASException

addValue

public IMetadataValue addValue(URI dataType)
                        throws IdASException,
                               InvalidTypeException

Creates a new value for this metadata element. This method is useful when the caller doesn't know whether the URI specified in the dataType param will build an ITypedValue or IComplexMetaValue. Otherwise callers will typically call addSimpleValue(URI, Object) or addComplexValue(URI) This call is typically followed by a call to IMetadataValue.isSimple() on the returned IMetadataValue. When found to be an ISimpleMetaValue, ITypedValue.setData(Object) is typically called on the returned IMetadataValue (cast as an ISimpleMetaValue). When found to be an IComplexMetaValue, one typically calls IHasMetadata.addMetadata(URI) on the returned IMetadataValue (cast as an IComplexMetaValue or IHasMetadata). Note: This operation is only applied to any backing data store after IContext.applyUpdates() is called.

Parameters:

dataType - The URI specifying the data type of Value being created

Throws:

{@link - IdASException}

{@link - InvalidTypeException} when the type is invalid

IdASException

InvalidTypeException

addValue

public IMetadataValue addValue(IMetadataValue copyFrom)
                        throws IdASException

Creates a new value for this metadata element by copying the passed IMetadataValue Note: This operation is only applied to any backing data store after IContext.applyUpdates() is called.

Parameters:

copyFrom - The IMetadataValue from which data is copied to create the returned IMetadataValue

Throws:

{@link - IdASException}

IdASException

addSimpleValue

public ISimpleMetaValue addSimpleValue(URI dataType,
                                       Object data)
                                throws IdASException,
                                       InvalidTypeException

Creates a new simple value for this metadata element. Note: This operation is only applied to any backing data store after IContext.applyUpdates() is called.

Parameters:

dataType - The URI specifying the type of Value being created

data - The data of the metadata value

Throws:

{@link - IdASException}

{@link - InvalidTypeException} when the type is invalid

IdASException

InvalidTypeException

addComplexValue

public IComplexMetaValue addComplexValue(URI dataType)
                                  throws IdASException,
                                         InvalidTypeException

Creates a new complex value for this metadata element. This call is typically followed by one or more calls to IHasMetadata.addMetadata(java.net.URI) on the returned IComplexMetaValue. Note: This operation is only applied to any backing data store after IContext.applyUpdates() is called.

Parameters:

dataType - The URI specifying the type of complex value being created

Throws:

{@link - IdASException}

{@link - InvalidTypeException} when the type is invalid

IdASException

InvalidTypeException

remove

public void remove()
            throws IdASException

Removes this metadata element from its container Note: This operation is only applied to any backing data store after IContext.applyUpdates() is called.

Throws:

{@link - IdASException}

IdASException

getModel

public IMetadataModel getModel()
                        throws IdASException

Returns a model of this type of metadata as it defined in the context's schema. The returned model could be used to analyze the metadata's type and discover what its value model is.

Returns:

a model of this type of metadata

Throws:

IdASException

isSingleValued

public boolean isSingleValued()
                       throws IdASException

Convenience method which returns true when the model for this metadata dictates that only a single value may exist. This is analogous to calling

 (myMetadata.getModel().getMaxCardinality() == 1) 
 

Returns:

boolean. When true, this object may be cast to an ISingleValuedMetadata

Throws:

IdASException

equals

public boolean equals(IMetadata meta)
               throws IdASException

Returns true if the passed metadata is equal to this one. The Metadata id's are compared, and all values are compared for equality

Parameters:

meta - the metadata to be compared to this one

Returns:

true if the passed metadata is equal to this metadata.

Throws:

IdASException