com.sleepycat.dbxml
Class XmlIndexSpecification

java.lang.Object
  com.sleepycat.dbxml.XmlIndexSpecification

public class XmlIndexSpecification
extends Object

The encapsulation of the indexing specification of a container. An indexing specification can be retrieved with the XmlContainer.getIndexSpecification() method, and modified using the XmlContainer.setIndexSpecification(com.sleepycat.dbxml.XmlIndexSpecification) method.

Note that adding an index to a container results in re-indexing all of the documents in that container, which can take a very long time. It is good practice to design an application to add useful indices before populating a container. Automatic indexing (setAutoIndexing(boolean)) results in implicit addition of indexes for leaf elements and attributes of newly-inserted content, resulting in reindexing as such new content is added. This behavior is on by default in order to provide simpler "hands-off" index addition. Applications that need to assert finer control over indexes should disable this behavior using setAutoIndexing(boolean) and explicitly add indexes.

The class is implemented using a handle-body idiom. When a handle is copied both handles maintain a reference to the same body.

This object is not thread-safe, and can only be safely used by one thread at a time in an application.

Field Summary

static int	KEY_EQUALITY Equality key type.
static int	KEY_NONE No key type.
static int	KEY_PRESENCE Presence key type.
static int	KEY_SUBSTRING Substring key type.
static int	NODE_ATTRIBUTE Attribute node type.
static int	NODE_ELEMENT Element node type.
static int	NODE_METADATA Metadata node type.
static int	NODE_NONE No node type.
static int	PATH_EDGE Edge path type.
static int	PATH_NODE Node path type.
static int	PATH_NONE No path type.
static int	UNIQUE_OFF The indexed value need not be unique container-wide
static int	UNIQUE_ON The indexed value must be unique container-wide

Constructor Summary

XmlIndexSpecification()

Method Summary

void	addDefaultIndex(int type, int syntax) Adds an indexing strategy to the default index specification.
void	addDefaultIndex(String index) Adds a single indexing strategy to the default index.
void	addIndex(String uri, String name, int type, int syntax) Identifies an indexing strategy to set for the identified node.
void	addIndex(String uri, String name, String index) Adds an index to the index specification.
void	delete() Free the native resources associated with this object.
void	deleteDefaultIndex(int type, int syntax) Delete the identified index from the default index specification.
void	deleteDefaultIndex(String index) Deletes one or more indexing strategies to the default index.
void	deleteIndex(String uri, String name, int type, int syntax) Deletes a single index strategy from the identified node.
void	deleteIndex(String uri, String name, String index) Deletes indexing strategies for a named document or metadata node.
XmlIndexDeclaration	find(String uri, String name) Returns the indexing strategies for a named document or metadata node.
boolean	getAutoIndexing() Retrieves the current state of automatic indexing.
String	getDefaultIndex() Retrieves the default index.
static int	getValueType(String index) Gets the XmlValue type specified in the given index string.
XmlIndexDeclaration	next() Obtains the next index in the XmlIndexSpecification.
void	replaceDefaultIndex(int type, int syntax) Replaces the default indexing strategy for the container.
void	replaceDefaultIndex(String index) Identifies one or more indexing strategies to set for the default index.
void	replaceIndex(String uri, String name, int type, int syntax) Replaces the indexing strategies for a named document or metadata node.
void	replaceIndex(String uri, String name, String index) Replaces the indexing strategies for a named document or metadata node.
void	reset() Resets the index specification iterator to the beginning of the index list.
void	setAutoIndexing(boolean value) Sets the state of automatic indexing to the specified value.

Methods inherited from class java.lang.Object

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

Field Detail

UNIQUE_OFF

public static final int UNIQUE_OFF

The indexed value need not be unique container-wide

See Also:

Constant Field Values

UNIQUE_ON

public static final int UNIQUE_ON

The indexed value must be unique container-wide

See Also:

Constant Field Values

PATH_NONE

public static final int PATH_NONE

No path type.

See Also:

Constant Field Values

PATH_NODE

public static final int PATH_NODE

Node path type.

See Also:

Constant Field Values

PATH_EDGE

public static final int PATH_EDGE

Edge path type.

See Also:

Constant Field Values

NODE_NONE

public static final int NODE_NONE

No node type.

See Also:

Constant Field Values

NODE_ELEMENT

public static final int NODE_ELEMENT

Element node type.

See Also:

Constant Field Values

NODE_ATTRIBUTE

public static final int NODE_ATTRIBUTE

Attribute node type.

See Also:

Constant Field Values

NODE_METADATA

public static final int NODE_METADATA

Metadata node type.

See Also:

Constant Field Values

KEY_NONE

public static final int KEY_NONE

No key type.

See Also:

Constant Field Values

KEY_PRESENCE

public static final int KEY_PRESENCE

Presence key type.

See Also:

Constant Field Values

KEY_EQUALITY

public static final int KEY_EQUALITY

Equality key type.

See Also:

Constant Field Values

KEY_SUBSTRING

public static final int KEY_SUBSTRING

Substring key type.

See Also:

Constant Field Values

Constructor Detail

XmlIndexSpecification

public XmlIndexSpecification()

Method Detail

delete

public void delete()

Free the native resources associated with this object.

addIndex

public void addIndex(String uri,
                     String name,
                     int type,
                     int syntax)
              throws XmlException

Identifies an indexing strategy to set for the identified node. The strategy is set using enumeration values for the index and the syntax.

Parameters:

uri - The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.

name - The name of the element or attribute node to be indexed.

type - A series of values bitwise OR'd together to form the index strategy.

To indicate whether the indexed value must be unique container-wide, use one of the following, or leave the value out entirely:

• UNIQUE_OFF
• UNIQUE_ON

To identify the path type, use one of the following:

• PATH_NODE
• PATH_EDGE

To identify the node type, use one of the following:

• NODE_ELEMENT
• NODE_ATTRIBUTE
• NODE_METADATA

Note that if NODE_METADATA is used, then PATH_NODE must also be used as well.

To identify the key type, use one of the following:

• KEY_PRESENCE
• KEY_EQUALITY
• KEY_SUBSTRING

For example:

XmlIndexSpecification.PATH_NODE | XmlIndexSpecification.NODE_ELEMENT | XmlIndexSpecification.KEY_SUBSTRING

syntax - Identifies the type of information being indexed. The value must be one of the XmlValue enumerated types:

• XmlValue.NONE
• XmlValue.BASE_64_BINARY
• XmlValue.BOOLEAN
• XmlValue.DATE
• XmlValue.DATE_TIME
• XmlValue.DECIMAL
• XmlValue.DOUBLE
• XmlValue.DURATION
• XmlValue.FLOAT
• XmlValue.G_DAY
• XmlValue.G_MONTH
• XmlValue.G_MONTH_DAY
• XmlValue.G_YEAR
• XmlValue.G_YEAR_MONTH
• XmlValue.HEX_BINARY
• XmlValue.STRING
• XmlValue.TIME

Note that if KEY_PRESENCE is specified for type, then this parameter must be XmlValue.NONE.

Throws:

XmlException

addIndex

public void addIndex(String uri,
                     String name,
                     String index)
              throws XmlException

Adds an index to the index specification. You then set the index specification using XmlContainer.setIndexSpecification(com.sleepycat.dbxml.XmlIndexSpecification).

You identify the indexing strategy that you want to add to the index specification in one of two ways. The first way is to provide a string that identifies the desired indexing strategy. The second is to use XmlIndexSpecification and XmlValue class constants to identify the same information.

Either way, an index strategy is set by providing the name of a node and one or more indexing strategies for that node. The node name can be either that of an element, attribute, or metadata node. Metadata nodes are used only for indexing metadata. Element and attribute nodes are used for indexing XML document content. For example, in the XML fragment:

"<art title='...'/>"

there are two node names that index strategies could be specified for, the element node name is 'art', and the attribute node name is 'title'.

When specifying indexing strategies, you must provide the following information:

• Whether the index value must be unique. Of all the information you provide for an index strategy, this is the only one you are not required to specify. If it is not specified, then the indexed value is not required to be unique.
• Whether the index is for a specific node, or whether it is for an edge. An edge occurs in an XML document when two nodes meet in the document. For example, in the document:

  "<a><b><c>foo</c>o</b></a>"

  there is an edge at <a><b> and another one at <b><c>.
• Whether the node to be indexed is an element, attribute, or metadata node. If you are indexing a metadata node, then the index must be a node index (not an edge index).
• Whether the index is a presence index (the index indicates whether the node or node edge exists in the document), an equality index (the index tracks the exact value set for the node), or an substring index (the index tracks all the substrings, 3 characters long and greater, that can be constructed for the node).
• The indexed value's syntax. There is a large list of available syntaxes, and they range everywhere from a boolean to a date to time information.

In addition to setting index strategies for specified nodes, applications can also specify a default indexing strategy for all nodes in a container by using addDefaultIndex(int, int). When a container is first created the default indexing strategy is 'unique-node-metadata-equality-string'.

For more information on designing an indexing strategy for your application, see the Berkeley DB XML Getting Started Guide.

Parameters:

uri - The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.

name - The name of the element or attribute node to be indexed.

index - A comma-separated list of strings that represent the indexing strategy. The strings must contain the following information in the following order:

unique-{path type}-{node type}-{key type}-{syntax}

where:

unique indicates that the indexed value is unique in the container. If this keyword does not appear on the index string, then the indexed value is not required to be unique in the container.

{path type} is either node or edge.

{node type} is one of element, attribute, or metadata. If metadata is specified, then {path type} must be node.

{key type} is one of presence, equality, or substring.

{syntax} identifies the type of information being indexed. It must be one of the following values:

• none
• base64Binary
• boolean
• date
• dateTime
• decimal
• double
• duration
• float
• gDay
• gMonth
• gMonthDay
• gYear
• gYearMonth
• hexBinary
• string
• time

Note that if {key type} is presence, then {syntax} must be none or simply not specified.

For example, examples index strings are:

unique-node-element-presence

node-element-equality-string

edge-element-presence-none

node-element-equality-float

Throws:

XmlException

deleteIndex

public void deleteIndex(String uri,
                        String name,
                        int type,
                        int syntax)
                 throws XmlException

Deletes a single index strategy from the identified node.

Parameters:

uri - The namespace of the node for which you want the index deleted. The default namespace is selected by passing an empty string for the namespace.

name - The name of the element or attribute node to be indexed.

type - A series of values bitwise OR'd together to form the index strategy. See addIndex(String, String, int, int) for a complete description.

syntax -

Identifies the type of information being indexed. See addIndex(String, String, int, int) for a complete description.

Throws:

XmlException

deleteIndex

public void deleteIndex(String uri,
                        String name,
                        String index)
                 throws XmlException

Deletes indexing strategies for a named document or metadata node. To delete an index set for metadata, specify the URI and name used when the metadata was added to the document.

Parameters:

uri - The namespace of the node for which you want the index deleted. The default namespace is selected by passing an empty string for the namespace.

name - The name of the element or attribute node to be indexed.

index - A comma-separated list of strings that represent the indexing strategy. See addIndex(String, String, String) for a complete description.

Throws:

XmlException

replaceIndex

public void replaceIndex(String uri,
                         String name,
                         int type,
                         int syntax)
                  throws XmlException

Replaces the indexing strategies for a named document or metadata node. All existing indexing strategies for that node are deleted, and the indexing strategy identified by this method is set for the node.

Parameters:

uri - The namespace of the node for which you want the index replaced. The default namespace is selected by passing an empty string for the namespace.

name - The name of the element or attribute node to be indexed.

type - A series of values bitwise OR'd together to form the index strategy. See addIndex(String, String, int, int) for a complete description.

syntax -

Identifies the type of information being indexed. See addIndex(String, String, int, int) for a complete description.

Throws:

XmlException

replaceIndex

public void replaceIndex(String uri,
                         String name,
                         String index)
                  throws XmlException

Replaces the indexing strategies for a named document or metadata node. All existing indexing strategies for that node are deleted, and the indexing strategy identified by this method is set for the node.

Identifies one or more indexing strategies to set for the identified node. The strategies are identified using a space-separated listing of strings.

Parameters:

uri - The namespace of the node for which you want the index replaces. The default namespace is selected by passing an empty string for the namespace.

name - The name of the element or attribute node to be indexed.

index - A comma-separated list of strings that represent the indexing strategy. See addIndex(String, String, String) for a complete description.

Throws:

XmlException

addDefaultIndex

public void addDefaultIndex(int type,
                            int syntax)
                     throws XmlException

Adds an indexing strategy to the default index specification. That is, the index provided on this method is applied to all nodes in a container, except for those for which an explicit index is already declared.

Parameters:

type - A series of values bitwise OR'd together to form the index strategy. See addIndex(String, String, int, int) for a complete description.

syntax - Identifies the type of information being indexed. See addIndex(String, String, int, int) for a complete description.

Throws:

XmlException

addDefaultIndex

public void addDefaultIndex(String index)
                     throws XmlException

Adds a single indexing strategy to the default index.

Parameters:

index - A comma-separated list of strings that represent the indexing strategy. See addIndex(String, String, String) for a complete description.

Throws:

XmlException

deleteDefaultIndex

public void deleteDefaultIndex(int type,
                               int syntax)
                        throws XmlException

Delete the identified index from the default index specification. You can add additional indices to the default index specification using addDefaultIndex(int, int).

Parameters:

type - A series of values bitwise OR'd together to form the index strategy. See addIndex(String, String, int, int) for a complete description.

syntax -

Identifies the type of information being indexed. See addIndex(String, String, int, int) for a complete description.

Throws:

XmlException

deleteDefaultIndex

public void deleteDefaultIndex(String index)
                        throws XmlException

Deletes one or more indexing strategies to the default index.

Parameters:

index - A comma-separated list of strings that represent the indexing strategy. See addIndex(String, String, String) for a complete description.

Throws:

XmlException

replaceDefaultIndex

public void replaceDefaultIndex(int type,
                                int syntax)
                         throws XmlException

Replaces the default indexing strategy for the container. The default index specification is used for all nodes in a document. You can add additional indices for specific document nodes using addIndex(java.lang.String, java.lang.String, int, int).

Parameters:

type - A series of values bitwise OR'd together to form the index strategy. See addIndex(String, String, int, int) for a complete description.

syntax -

Identifies the type of information being indexed. See addIndex(String, String, int, int) for a complete description.

Throws:

XmlException

replaceDefaultIndex

public void replaceDefaultIndex(String index)
                         throws XmlException

Identifies one or more indexing strategies to set for the default index. The strategies are identified as a space-separated listing of strings.

Parameters:

index - A comma-separated list of strings that represent the indexing strategy. See addIndex(String, String, String) for a complete description.

Throws:

XmlException

reset

public void reset()
           throws XmlException

Resets the index specification iterator to the beginning of the index list. Use next() to iterate through the indices contained in the index specification.

Throws:

XmlException

find

public XmlIndexDeclaration find(String uri,
                                String name)
                         throws XmlException

Returns the indexing strategies for a named document or metadata node. This method returns an XmlIndexDeclaration object if an index for the node is found; otherwise it returns null.

Parameters:

uri - The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.

name - The name of the element or attribute node to be indexed.

Throws:

XmlException

next

public XmlIndexDeclaration next()
                         throws XmlException

Obtains the next index in the XmlIndexSpecification. Use reset() to reset this iterator.

This method returns null if no additional indices exist in the index list.

Throws:

XmlException

getDefaultIndex

public String getDefaultIndex()
                       throws XmlException

Retrieves the default index. The default index is the index used by all nodes in the document in the absence of any other index.

Throws:

XmlException

setAutoIndexing

public void setAutoIndexing(boolean value)

Sets the state of automatic indexing to the specified value. The change will not have any effect unless XmlContainer.setIndexSpecification(com.sleepycat.dbxml.XmlIndexSpecification) is called with this object.

Parameters:

value - set to true to enable automatic index addition

getValueType

public static int getValueType(String index)
                        throws XmlException

Gets the XmlValue type specified in the given index string.

Parameters:

index - The index string.

Returns:

The XmlValue type, which consists of

• XmlValue.NONE
• XmlValue.BASE_64_BINARY
• XmlValue.BOOLEAN
• XmlValue.DATE
• XmlValue.DATE_TIME
• XmlValue.DECIMAL
• XmlValue.DOUBLE
• XmlValue.DURATION
• XmlValue.FLOAT
• XmlValue.G_DAY
• XmlValue.G_MONTH
• XmlValue.G_MONTH_DAY
• XmlValue.G_YEAR
• XmlValue.G_YEAR_MONTH
• XmlValue.HEX_BINARY
• XmlValue.STRING
• XmlValue.TIME

Throws:

XmlException

getAutoIndexing

public boolean getAutoIndexing()

Retrieves the current state of automatic indexing.