org.ocap.hn.content
Class MetadataNode

java.lang.Object
  org.ocap.hn.content.MetadataNode

public abstract class MetadataNode
extends Object

A collection of metadata entries, each of which is a key/value pair where the key identifies a property and the value is the property value, and a collection of supporting namespace declarations. Each property may have an ExtendedFileAccessPermissions defining its accessibility. Property values (also called metadata) can be MetadataNodes; thus treelike metadata structures are supported.

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 nested MetadataNodes directly by concatenating the different keys using # to separate them. In the above example, 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

protected

MetadataNode() Constructor; only to be invoked by subclass constructors.

Method Summary

abstract void	addMetadata(String key, Object value) Adds a new metadata entry, modifies an existing metadata entry, or removes an existing metadata entry.
abstract void	addMetadata(String key, Object value, org.ocap.storage.ExtendedFileAccessPermissions efap) Adds a new metadata entry, modifies an existing metadata entry, or removes an existing metadata entry, with specification of ExtendedFileAccessPermissions.
abstract void	addNameSpace(String namespace, String URI) Adds a namespace declaration to this MetadataNode.
static MetadataNode	createMetadataNode() Creates a MetadataNode.
static MetadataNode	createMetadataNode(String key) Deprecated. Replaced by createMetadataNode(). Creates a MetadataNode.
abstract org.ocap.storage.ExtendedFileAccessPermissions	getExtendedFileAccessPermissions(String key) Gets the ExtendedFileAccessPermissions for the property identified by the specified key.
abstract String	getKey() Gets the key string, which can be utilized to retrieve this MetadataNode from its parent.
abstract String[]	getKeys() Gets the keys for all top-level metadata in this MetadataNode.
abstract Enumeration	getMetadata() Gets an Enumeration of all top-level metadata in this MetadataNode.
abstract Object	getMetadata(String key) Gets a reference to the value associated with the specified key, if any.
abstract MetadataNode	getParentNode() Gets the parent MetadataNode of this MetadataNode.

Methods inherited from class java.lang.Object

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

Constructor Detail

MetadataNode

protected MetadataNode()

Constructor; only to be invoked by subclass constructors.

Method Detail

createMetadataNode

public static MetadataNode createMetadataNode()

Creates a MetadataNode.

Returns:

The newly created MetadataNode.

createMetadataNode

public static MetadataNode createMetadataNode(String key)

Deprecated. Replaced by createMetadataNode(). Creates a MetadataNode.

Parameters:

key - Unused. (In particular, it SHALL NOT be used to set the key string retrievable by the getKey method.)

Returns:

The newly created MetadataNode.

getMetadata

public abstract Object getMetadata(String key)

Gets a reference to the value associated with the specified key, if any.

In order to query metadata in a hierarchy, query strings like IDENT1#IDENT2#IDENT3 are possible, where IDENT1 maps to a MetadataNode in this MetadataNode, IDENT2 a MetadataNode in the IDENT1 MetadataNode, and IDENT3 an Object in the IDENT2 MetadataNode.

This method only returns locally cached metadata. This method SHALL NOT cause network activity.

Parameters:

key - The key.

Returns:

A reference to the value associated with the key, or null if there is none.

Throws:

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

addMetadata

public abstract void addMetadata(String key,
                                 Object value)

Adds a new metadata entry, modifies an existing metadata entry, or removes an existing metadata entry.

If the key argument does not contain an "@" character, the value argument must be either null or a reference to an instance of one of the following classes:

• org.dvb.application.AppID
• org.ocap.storage.ExtendedFileAccessPermissions
• a class extending org.ocap.hn.content.MetadataNode and not implementing java.io.Serializable
• a nonarray class implementing java.io.Serializable
• T[], where T is one of the above

If the key argument contains an "@" character but does not begin with an "@" character, the value argument must be either null or a reference to an instance of one of the following classes:

• java.lang.String
• java.lang.String[]

If the key argument begins with an "@" character, the value argument must be either null or a reference to an instance of the following class:

• java.lang.String

If the value argument is null or a reference to a zero-length array, any existing value associated with the key argument SHALL be removed. Otherwise, if a value is already associated with the key argument, the value argument's referent SHALL replace that value; if not, the value argument's referent SHALL be associated with the key argument.

Keys MAY contain a namespace prefix as part of their definition. Namespace prefixes SHALL appear in keys as a colon separated prefix in the key (e.g. upnp:class). Vendor-specific namespace prefixes MUST be declared in this MetadataNode using the addNameSpace method prior to usage in this method, or be a valid namespace prefix 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 closest containing ContentEntry, if there is one.

Parameters:

key - The key, e.g. "TITLE". When the value argument is a reference to an instance of a class extending MetadataNode, the implementation SHALL set that MetadataNode's key string retrievable by the getKey method to this key.

value - Null or a reference to the value to associate with the key.

Throws:

IllegalArgumentException - if the key argument contains an undeclared namespace prefix or a "#" character, or if the value argument is neither null nor a reference to an instance of an acceptable class, or if the value argument is a reference to an instance of a class that implements java.io.Serializable but that instance cannot be successfully serialized.

SecurityException - if the property identified by the key argument does not exist and the calling application does not have sufficient file access permissions to write to the ContentEntry containing this MetadataNode, or if the property identified by the key argument does exist and the calling application does not have sufficient file access permissions to write to 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, modifies an existing metadata entry, or removes an existing metadata entry, with specification of ExtendedFileAccessPermissions.

If the key argument does not contain an "@" character, the value argument must be either null or a reference to an instance of one of the following classes:

• org.dvb.application.AppID
• org.ocap.storage.ExtendedFileAccessPermissions
• a class extending org.ocap.hn.content.MetadataNode and not implementing java.io.Serializable
• a nonarray class implementing java.io.Serializable
• T[], where T is one of the above

If the key argument contains an "@" character but does not begin with an "@" character, the value argument must be either null or a reference to an instance of one of the following classes:

• java.lang.String
• java.lang.String[]

If the key argument begins with an "@" character, the value argument must be either null or a reference to an instance of the following class:

• java.lang.String

If the value argument is null or a reference to a zero-length array, any existing value associated with the key argument SHALL be removed. Otherwise, if a value is already associated with the key argument, the value argument's referent SHALL replace that value; if not, the value argument's referent SHALL be associated with the key argument.

Keys MAY contain a namespace prefix as part of their definition. Namespace prefixes SHALL appear in keys as a colon separated prefix in the key (e.g. upnp:class). Vendor-specific namespace prefixes MUST be declared in this MetadataNode using the addNameSpace method prior to usage in this method, or be a valid namespace prefix 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 argument.

Parameters:

key - The key, e.g. "TITLE". When the value argument is a reference to an instance of a class extending MetadataNode, the implementation SHALL set that MetadataNode's key string retrievable by the getKey method to this key.

value - Null or a reference to the value to associate with the key.

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

Throws:

IllegalArgumentException - if the key argument contains an undeclared namespace prefix or a "#" character, or if the value argument is neither null nor a reference to an instance of an acceptable class, or if the value argument is a reference to an instance of a class that implements java.io.Serializable but that instance cannot be successfully serialized, or if the efap argument is null.

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

See Also:

addNameSpace(String namespace, String URI)

addNameSpace

public abstract void addNameSpace(String namespace,
                                  String URI)

Adds a namespace declaration to this MetadataNode. Once a namespace is declared, its prefix SHALL be valid as a metadata key qualifier for this MetadataNode and any of its descendants.

Parameters:

namespace - The namespace prefix (e.g. "av").

URI - The namespace name (e.g. "urn:schemas-upnp-org:av:av").

getMetadata

public abstract Enumeration getMetadata()

Gets an Enumeration of all top-level metadata in this MetadataNode.

This method only returns an Enumeration of locally cached metadata. This method SHALL NOT cause network activity.

Returns:

An Enumeration of all top-level metadata in this MetadataNode.

getParentNode

public abstract MetadataNode getParentNode()

Gets the parent MetadataNode of this MetadataNode.

Returns:

The parent MetadataNode of this MetadataNode, or null if there is none.

getKey

public abstract String getKey()

Gets the key string, which can be utilized to retrieve this MetadataNode from its parent. If this MetadataNode has no parent, this method SHALL return null.

Returns:

The key string associated with this MetadataNode.

getKeys

public abstract String[] getKeys()

Gets the keys for all top-level metadata in this MetadataNode.

This method only returns the keys for locally cached metadata. This method SHALL NOT cause network activity.

Returns:

An array of Strings that are the keys for all top-level metadata in this MetadataNode.

getExtendedFileAccessPermissions

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

Gets the ExtendedFileAccessPermissions for the property identified by the specified key.

In order to query metadata in a hierarchy, query strings like IDENT1#IDENT2#IDENT3 are possible, where IDENT1 maps to a MetadataNode in this MetadataNode, IDENT2 a MetadataNode in the IDENT1 MetadataNode, and IDENT3 an Object in the IDENT2 MetadataNode.

Parameters:

key - The key identifying the property to get the ExtendedFileAccessPermissions for.

Returns:

The ExtendedFileAccessPermissions of the property identified by the key, or null if there is no such property or if the property has no ExtendedFileAccessPermissions.