org.ocap.hn.content

Class MetadataNode

java.lang.Object

org.ocap.hn.content.MetadataNode

public abstract class MetadataNode
extends Object

Base class for all Metadata. Metadata can be a normal java.lang.String, any serializable Object, another MetadataNode for tree like meta data structures or other Objects declared as supported by this specification. One example is given below:

 RootNode
 |
 --- TITLE - String("Best Movie Ever")
 |
 --- CREW  - MetadataNode
                 |
                 --- MAIN_ACTOR - String("Joe Sixpack")
                 |
                 --- MAIN_ACTOR2 - String("Doris Dosenkohl")
 |
 --- SYNOPSIS - String("Don't know - I fell asleep after 5 seconds")
  

It is possible to get Metadata from other MetadataNodes directly by concatenating the different identifiers using # to separate them.
e.g. getMetadata("CREW#MAIN_ACTOR") would return "Joe Sixpack"

The MetadataNode represents the current snapshot of metadata associated with a network entity as cached on the local device. This may or may not reflect an accurate or complete view of the metadata that exists on the network. It is the responsibility of the application to explicitly update metadata using the home network APIs (e.g. ContentServerNetModule.requestSearchEntries(String, String, int, int, String, String, org.ocap.hn.NetActionHandler)

Constructor Summary

Constructors

Constructor and Description
MetadataNode()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	addMetadata(String key, Object value) Adds a new metadata entry to this MetadataNode or modifies an existing metadata entry in this MetadataNode.
abstract void	addMetadata(String key, Object value, org.ocap.storage.ExtendedFileAccessPermissions efap) Adds a new metadata entry to this MetadataNode or modifies an existing metadata entry in this MetadataNode.
abstract void	addNameSpace(String namespace, String URI) Adds a namespace definition to this MetadataNode.
static MetadataNode	createMetadataNode(String key) Creates an instance of a MetadataNode object.
abstract org.ocap.storage.ExtendedFileAccessPermissions	getExtendedFileAccessPermissions(String key) Gets the extended file access permissions for a property.
abstract String	getKey() Gets the key string which can be utilized to retrieve this MetadataNode from this node's parent.
abstract String[]	getKeys() Gets the set of keys for all metadata contained within this MetadataNode.
abstract Enumeration	getMetadata() Gets an Enumeration of all metadata objects in this node.
abstract Object	getMetadata(String key) Returns the Metadata for the specified key.
abstract MetadataNode	getParentNode() Gets the parent node of this MetadataNode.

Methods inherited from class java.lang.Object

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

Constructor Detail

MetadataNode

public MetadataNode()

Method Detail

createMetadataNode

public static MetadataNode createMetadataNode(String key)

Creates an instance of a MetadataNode object. When added to another MetadataNode, this node can be located using the key specified in the constructor.

Parameters:

key - the key for locating this MetadataNode

Returns:

the newly created MetadataNode

getMetadata

public abstract Object getMetadata(String key)

Returns the Metadata for the specified key. The returned object can be a normal String (e.g. for title etc), a java.awt.Image, a Vector containing a list of elements, another MetadataNode for tree like metadata structures or other tbd. Objects. In order to query a Metadata in a hierarchy query strings like
IDENT1#IDENT2#IDENT3 are possible where IDENT1 is a MetadataNode in this node, IDENT2 a MetadataNode in IDENT2 and IDENT3 an object in IDENT2. Performs a local cache search only. This method only returns locally cached metadata. This method SHALL not cause network activity.

Parameters:

key - The key to search for.

Returns:

The value associated with the key or null if no match found.

Throws:

SecurityException - if the calling application does not have extended file access permission to read from the property represented by the key parameter.

addMetadata

public abstract void addMetadata(String key,
               Object value)

Adds a new metadata entry to this MetadataNode or modifies an existing metadata entry in this MetadataNode. The value Object to be added to this metadata node MUST be of a type for which a known network mapping exists. All objects implementing the Serializable interface are considered to have a known network mapping. In addition, the following classes have a known network mapping:
org.dvb.application.AppID
org.ocap.storage.ExtendedFileAccessPermissions
org.ocap.hn.content.ContentContainer
org.ocap.hn.content.MetadataNode

If the Object to be added is an instance of MetadataNode, all Objects contained within that MetadataNode SHALL be recursively added to this MetadataNode as a result of this operation.

Invocation of this method SHALL replace any values already present for the given key paramaeter. If a value Object is already associated with the key string passed into this method, the value passed in by this method SHALL replace the existing value. If a value of null is passed into this method, any existing value assocaited with the key passed into this method SHALL be removed. Keys MAY contain a namespace as part of their definition. Namespaces SHALL appear in keys as a colon separated prefix in the key string (e.g. "namespace:key"). Vendor specific namespaces MUST be added to this MetadataNode using the addNameSpace() method prior to usage in this method, or be a valid namespace in any containing parent MetadataNode. Each property added by this method whether new or pre-existing SHALL be given an ExtendedFileAccessPermissions that matches that of the parent ContentEntry.

Parameters:

key - The key e.g. "TITLE". When the value type is MetadataNode the implementation SHALL over-write the key set by the createMetadataNode method with the value of this parameter.

value - The value associated with the key, e.g. "When Harry Meets Sally" or a more complex Object like another MetadataNode.

Throws:

IllegalArgumentException - if value is not a known mappable object type, or if the key parameter contains an unknown vendor defined namespace .

SecurityException - if the property identified by the key parameter does not exist and the calling application does not have sufficient file access permissions to write to the ContentEntry containing this MetadataNode.

SecurityException - if the property identified by the key parameter does exist and the calling application does not have sufficient file access permissions to write to the the property.

See Also:

addNameSpace(String namespace, String URI)

addMetadata

public abstract void addMetadata(String key,
               Object value,
               org.ocap.storage.ExtendedFileAccessPermissions efap)

Adds a new metadata entry to this MetadataNode or modifies an existing metadata entry in this MetadataNode. The value Object to be added to this metadata node MUST be of a type for which a known network mapping exists. All objects implementing the Serializable interface are considered to have a known network mapping. In addition, the following classes have a known network mapping:
org.dvb.application.AppID
org.ocap.storage.ExtendedFileAccessPermissions
org.ocap.hn.content.ContentContainer
org.ocap.hn.content.MetadataNode

If the Object to be added is an instance of MetadataNode, all Objects contained within that MetadataNode SHALL be recursively added to this MetadataNode as a result of this operation.

Invocation of this method SHALL replace any values already present for the given key paramaeter. If a value Object is already associated with the key string passed into this method, the value passed in by this method SHALL replace the existing value. If a value of null is passed into this method, any existing value assocaited with the key passed into this method SHALL be removed. Keys MAY contain a namespace as part of their definition. Namespaces SHALL appear in keys as a colon separated prefix in the key string (e.g. "namespace:key"). Vendor specific namespaces MUST be added to this MetadataNode using the addNameSpace() method prior to usage in this method, or be a valid namespace in any containing parent MetadataNode. Each property added by this method whether new or pre-existing SHALL be given an ExtendedFileAccessPermissions that matches the efap parameter.

Parameters:

key - The key e.g. "TITLE". When the value type is MetadataNode the implementation SHALL over-write the key set by the createMetadataNode method with the value of this parameter.

value - The value associated with the key, e.g. "When Harry Meets Sally" or a more complex Object like another MetadataNode.

efap - ExtendedFileAccessPermissions for the property or properties added or modified by this method.

Throws:

IllegalArgumentException - if value is not a known mappable object type, or if the key parameter contains an unknown vendor defined namespace, or if the efap parameter is null.

SecurityException - if the property identified by the key parameter does not exist and the calling application does not have sufficient file access permissions to write to the ContentEntry containing this MetadataNode.

SecurityException - if the property identified by the key parameter does exist and the calling application does not have sufficient file access permissions to write to the the property.

See Also:

addNameSpace(String namespace, String URI)

addNameSpace

public abstract void addNameSpace(String namespace,
                String URI)

Adds a namespace definition to this MetadataNode. Once added, this namespace SHALL be valid as a metadata key qualifier for this node and any children and sub-children of this MetadataNode.

Parameters:

namespace - String identifier of the namespace to be added

URI - vendor specific String based universal resource indicator pointing to the definition of this namespace.

See Also:

addMetadata(String key,Object value)

getMetadata

public abstract Enumeration getMetadata()

Gets an Enumeration of all metadata objects in this node. The enumeration SHALL contain the top-level MetadataNode objects which MAY contain other MetadataNode objects. This method only returns locally cached metadata. This method SHALL not cause network activity.

Returns:

Enumeration of top-level MetadataNode objects.

getParentNode

public abstract MetadataNode getParentNode()

Gets the parent node of this MetadataNode.

Returns:

Parent of this node.

getKey

public abstract String getKey()

Gets the key string which can be utilized to retrieve this MetadataNode from this node's parent. If this MetadataNode is a root MetadataNode, the method SHALL return null.

Returns:

the key string associated with this MetadataNode

getKeys

public abstract String[] getKeys()

Gets the set of keys for all metadata contained within this MetadataNode.

Returns:

an array of Strings representing metadata contained within this MetadataNode

getExtendedFileAccessPermissions

public abstract org.ocap.storage.ExtendedFileAccessPermissions getExtendedFileAccessPermissions(String key)

Gets the extended file access permissions for a property.

Parameters:

key - The key value representing the property to get the permissions for.

Returns:

The extended file access permissions of the property or null if the key does not match a known property.