Skip navigation links

Oracle® Database XML Java API Reference
12c Release 1 (12.1)

E15981-09


oracle.xml.xquery
Class OXQEntity

java.lang.Object
  extended by oracle.xml.xquery.OXQEntity

All Implemented Interfaces:
java.lang.Cloneable, OXQCloseable

public final class OXQEntity
extends java.lang.Object
implements OXQCloseable, java.lang.Cloneable

The entity returned by an OXQEntityResolver. The entity is made up of a data object, a media-type, and a set of properties. The type of data depends on the kind of entity that is being resolved. The following sections describe what data is expected to be for the possible entity kinds.

Schema Entities (OXQEntityKind.SCHEMA)

Type of data Description
java.io.InputStream
java.io.Reader
java.lang.String
javax.xml.transform.Source
A schema will be obtained by parsing data as an XML Schema.
javax.xml.xquery.XQItem A schema will be obtained by treating data as a parsed XML Schema.
An array or java.util.Collection of any of the above types. One or more schemas will be obtained by treating each object in the array/collection as described above.

The media-type is currently ignored for schemas but it may be used in future releases. All schemas returned must have the target namespace that was specified in the OXQEntityLocator instance passed to the entity resolver.

Module Entities (OXQEntityKind.MODULE)

Type of data Description
java.io.InputStream
java.io.Reader
java.lang.String
javax.xml.transform.Source
If the media-type is application/xquery+xml then data will be parsed as an XQueryX module. Otherwise, data will be parsed as an XQuery module.
javax.xml.xquery.XQItem If the media-type is application/xquery+xml then data will be will be treated as a parsed XQueryX module. Otherwise, data will be serialized as text and then parsed as an XQuery module.
An array or java.util.Collection of any of the above types. One or more modules will be obtained by treating each object in the array/collection as described above.

Document Entities (OXQEntityKind.DOCUMENT)

Type of data Description
java.io.InputStream
java.io.Reader
java.lang.String
javax.xml.transform.Source

A document will be obtained by parsing data.

The following media-types are supported:
It is an error to specify a binary media-type in combination with character data (i.e. Reader or String). When parsing, external XML entities (if any exist) will be resolved by additional calls to the entity resolver using the XML_ENTITY kind.
javax.xml.xquery.XQSequence The sequence must either be empty or contain a single document node. This will be used directly for the fn:doc or fn:collection function.
javax.xml.xquery.XQItem The item must be a document node. This will be used directly for the fn:doc or fn:collection function. Note, data may be null to signify the empty sequence.

See also:

Document Type Entities (OXQEntityKind.DOCUMENT_TYPE)

data must be an instance of java.xml.xquery.XQItemType that is a subtype of document-node(). The returned type will be used as the static type of the fn:doc function.

Collection Entities (OXQEntityKind.COLLECTION)

data must be an instance of java.util.Iterator<java.net.URI>. For each URI returned, the entity resolver will be called using the DOCUMENT entity kind to obtain a document node. The documents will be returned by the call to fn:collection.

Each document URI returned by the Iterator must be unique or an error will be raised. This uniqueness check may be disabled by setting property PROPERTY_COLLECTION_UNIQUE_CHECK to false on the returned entity using method setProperty(int, Object). Even if this check is disabled, the returned document URIs must still be unique or else the query results may be incorrect. Disabling the check may improve performance in cases where there are many document URIs.

External Function Entities (OXQEntityKind.EXTERNAL_FUNCTION)

Type of data Description
java.lang.Class The class must extend OXQFunctionEvaluator.
java.lang.Method The method must be static with parameter and return types that can be mapped to XQuery types as defined by XQJ specification.

The media-type is ignored in this case.

XML Entities (OXQEntityKind.XML_ENTITY)

data must be an instance of java.io.InputStream, java.xml.stream.XMLStreamReader, or java.xml.stream.XMLEventReader

Note, this kind is only used when the query processor needs to resolve an external XML entity while parsing unparsed XML returned for other entity kinds such as DOCUMENT.

upd:put Entities (OXQEntityKind.UPD_PUT)

data must be a class that extends OXQFunctionEvaluator. The returned class will be instantiated and then the evaluate method will be invoked. The first XQSequence argument provided is the node to store. The second XQSequence argument is an absolute URI (as xs:string) which is the location where the node should be stored. Each returned OXQFunctionEvaluator may be instantiated once and reused multiple times.

Note, at the time the evaluator is invoked all updates have been applied and will not be undone if the evaluate method raises an error.

Parser Factory Entities (OXQEntityKind.XML_PARSER_FACTORY)

data must be an instance of javax.xml.stream.XMLInputFactory.

See also:

DOM Factory Entities (OXQEntityKind.DOM_FACTORY)

data must be an instance of javax.xml.parsers.DocumentBuilderFactory.

Collation Entities (COLLATION)

data must be an instance of java.text.Collator or oracle.i18n.text.OraCollator. When a java.text.Collator is returned, the functions fn:contains, fn:starts-with, fn:ends-with, fn:substring-before, fn:substring-after will raise an error unless the returned Collator is also a java.text.RuleBasedCollator.

Closing resources

The entity returned by OXQEntityResolver can have closeable resources associated with it through OXQCloseable methods. The XQuery processor assumes ownership of these resources and guarantees that they are closed when the query execution finishes.

Since:
12.1

Field Summary
static int DOCUMENT_URI_HIDE
          A string value constant for PROPERTY_XML_PARSER_DOCUMENT_URI
static int DOCUMENT_URI_PASS
          A string value constant for PROPERTY_XML_PARSER_DOCUMENT_URI
static int DOCUMENT_URI_PASS_URL
          A string value constant for PROPERTY_XML_PARSER_DOCUMENT_URI
static java.lang.String MEDIA_TYPE_APPLICATION_XML
          Media-type "application/xml"
static java.lang.String MEDIA_TYPE_ORACLE_CSX
          Media-type "application/vnd.oracle.xml+csx"
static java.lang.String MEDIA_TYPE_ORACLE_XPATH
          Media-type "application/vnd.oracle.xml.xpath"
static java.lang.String MEDIA_TYPE_TEXT_XML
          Media-type "text/xml"
static java.lang.String MEDIA_TYPE_XQUERY
          Media-type "application/xquery"
static java.lang.String MEDIA_TYPE_XQUERYX
          Media-type "application/xquery+xml"
static int PROPERTY_COLLECTION_UNIQUE_CHECK
          The property that specifies whether or not the XQuery processor will ensure that the document URIs returned by a COLLECTION entity are unique.
static int PROPERTY_DOCUMENT_PAGE_MANAGER
          The property that specifies an instance of PageManager that will be used to store a DOCUMENT entity.
static int PROPERTY_INFOSET_COMMENTS
          The property that specifies whether comment nodes are preserved when converting XML to the XQuery data model.
static int PROPERTY_INFOSET_INSIGNIFICANT_WHITESPACE
          The property that specifies whether insignificant whitespace in an XML document is preserved or ignored when converting XML to the XQuery data model.
static int PROPERTY_INFOSET_NAMESPACES
          The property that specifies whether namespaces that are not known to be used are preserved when converting XML to the XQuery data model.
static int PROPERTY_INFOSET_SIGNIFICANT_WHITESPACE
          The property that specifies whether significant whitespace in an XML document is preserved or ignored when converting XML to the XQuery data model.
static int PROPERTY_MODULE_STATIC_CONTEXT
          The property that specifies an instance of XQStaticContext to be used with a returned MODULE entity.
static int PROPERTY_XML_PARSER_DETECT_ENCODING
          The property that specifies whether the XML parser performs document encoding detection or the encoding is detected by the XQuery processor.
static int PROPERTY_XML_PARSER_DOCUMENT_URI
          The property that specifies whether the XQuery processor passes the document URI to the XML parser or not.
static int PROPERTY_XML_PARSER_VALIDATING
          The property that specifies whether or not to use a validating XML parser (performing DTD validation).

 

Constructor Summary
OXQEntity(java.lang.Object data)
          Constructs an entity.
OXQEntity(java.lang.Object data, java.lang.String mediaType)
          Constructs an entity.

 

Method Summary
 OXQEntity clone()
          Standard override; no change in semantics.
 void enlistCloseable(java.io.Closeable closeable)
          Declares a closeable object that will be closed when this object is closed.
 void enlistCloseable(javax.xml.stream.XMLStreamReader closeable)
          Declares an XMLStreamReader object that will be closed when this object is closed.
 void enlistCloseable(XQSequence closeable)
          Declares an XQSequence object that will be closed when this object is closed.
 java.lang.Object getData()
          Returns the entity.
 java.lang.Object[] getEnlistedCloseables()
          Returns closeable resources associated with this entity.
 java.lang.String getMediaType()
          Returns the Media-Type of the entity
 java.lang.Object getProperty(int key)
          Returns the property value for the given property key.
 void setData(java.lang.Object data)
          Sets the entity.
 void setMediaType(java.lang.String mediaType)
          Sets the Media-Type of the entity.
 void setProperty(int key, java.lang.Object value)
          Sets additional processing options for this entity.

 

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Field Detail

MEDIA_TYPE_APPLICATION_XML

public static final java.lang.String MEDIA_TYPE_APPLICATION_XML
Media-type "application/xml"
See Also:
setMediaType(String), Constant Field Values

MEDIA_TYPE_TEXT_XML

public static final java.lang.String MEDIA_TYPE_TEXT_XML
Media-type "text/xml"
See Also:
setMediaType(String), Constant Field Values

MEDIA_TYPE_ORACLE_CSX

public static final java.lang.String MEDIA_TYPE_ORACLE_CSX
Media-type "application/vnd.oracle.xml+csx"
See Also:
setMediaType(String), Constant Field Values

MEDIA_TYPE_ORACLE_XPATH

public static final java.lang.String MEDIA_TYPE_ORACLE_XPATH
Media-type "application/vnd.oracle.xml.xpath"
See Also:
setMediaType(String), Constant Field Values

MEDIA_TYPE_XQUERY

public static final java.lang.String MEDIA_TYPE_XQUERY
Media-type "application/xquery"
See Also:
setMediaType(String), Constant Field Values

MEDIA_TYPE_XQUERYX

public static final java.lang.String MEDIA_TYPE_XQUERYX
Media-type "application/xquery+xml"
See Also:
setMediaType(String), Constant Field Values

PROPERTY_XML_PARSER_DOCUMENT_URI

public static final int PROPERTY_XML_PARSER_DOCUMENT_URI
The property that specifies whether the XQuery processor passes the document URI to the XML parser or not. Supported values are the following:
See Also:
OXQEntityKind.XML_PARSER_FACTORY, setProperty(int, Object), Constant Field Values

PROPERTY_XML_PARSER_DETECT_ENCODING

public static final int PROPERTY_XML_PARSER_DETECT_ENCODING
The property that specifies whether the XML parser performs document encoding detection or the encoding is detected by the XQuery processor. The property value must be an instance of java.lang.Boolean:
See Also:
OXQEntityKind.XML_PARSER_FACTORY, setProperty(int, Object), Constant Field Values

PROPERTY_XML_PARSER_VALIDATING

public static final int PROPERTY_XML_PARSER_VALIDATING
The property that specifies whether or not to use a validating XML parser (performing DTD validation). If XML parser doesn't support DTD validation property javax.xml.stream.XMLInputFactory.IS_VALIDATING then this option is ignored. The property value must be an instance of java.lang.Boolean:
See Also:
OXQEntityKind.DOCUMENT, setProperty(int, Object), Constant Field Values

PROPERTY_INFOSET_COMMENTS

public static final int PROPERTY_INFOSET_COMMENTS
The property that specifies whether comment nodes are preserved when converting XML to the XQuery data model. The property value must be an instance of java.lang.Boolean:
See Also:
OXQEntityKind.DOCUMENT, setProperty(int, Object), Constant Field Values

PROPERTY_INFOSET_NAMESPACES

public static final int PROPERTY_INFOSET_NAMESPACES
The property that specifies whether namespaces that are not known to be used are preserved when converting XML to the XQuery data model. See XDM : Element Nodes / Construction from Infoset for more information. The property value must be an instance of java.lang.Boolean:
See Also:
OXQEntityKind.DOCUMENT, setProperty(int, Object), Constant Field Values

PROPERTY_INFOSET_SIGNIFICANT_WHITESPACE

public static final int PROPERTY_INFOSET_SIGNIFICANT_WHITESPACE
The property that specifies whether significant whitespace in an XML document is preserved or ignored when converting XML to the XQuery data model. According to the XML specification, an XML parser can only detect whether whitespace in element content is significant or not if it's in validation mode (PROPERTY_XML_PARSER_VALIDATING). In non-validating mode the parser cannot make that decision and therefore will report all whitespace as significant. This option only controls significant whitespace handling. The property value must be an instance of java.lang.Boolean:
See Also:
OXQEntityKind.DOCUMENT, setProperty(int, Object), Constant Field Values

PROPERTY_INFOSET_INSIGNIFICANT_WHITESPACE

public static final int PROPERTY_INFOSET_INSIGNIFICANT_WHITESPACE
The property that specifies whether insignificant whitespace in an XML document is preserved or ignored when converting XML to the XQuery data model. According to the XML specification an XML parser can detect whether whitespace in element content is significant or not if it's in validation mode (PROPERTY_XML_PARSER_VALIDATING). This option only controls insignificant whitespace handling (also called element content whitespace). The property value must be an instance of java.lang.Boolean:
See Also:
OXQEntityKind.DOCUMENT, setProperty(int, Object), Constant Field Values

PROPERTY_COLLECTION_UNIQUE_CHECK

public static final int PROPERTY_COLLECTION_UNIQUE_CHECK
The property that specifies whether or not the XQuery processor will ensure that the document URIs returned by a COLLECTION entity are unique. Even if this check is disabled, the returned document URIs must still be unique or else the query results may be incorrect. Disabling the check may improve performance in cases where there are many document URIs. The property value must be an instance of java.lang.Boolean:
See Also:
OXQEntityKind.COLLECTION, setProperty(int, Object), Constant Field Values

PROPERTY_MODULE_STATIC_CONTEXT

public static final int PROPERTY_MODULE_STATIC_CONTEXT
The property that specifies an instance of XQStaticContext to be used with a returned MODULE entity. The property value must be an instance of XQStaticContext
See Also:
OXQEntityKind.MODULE, setProperty(int, Object), Constant Field Values

PROPERTY_DOCUMENT_PAGE_MANAGER

public static final int PROPERTY_DOCUMENT_PAGE_MANAGER
The property that specifies an instance of PageManager that will be used to store a DOCUMENT entity. The returned document will be copied into the PageManager. The pages will be released (deleted) when the query result is closed. The property value must be an instance of PageManager
See Also:
OXQEntityKind.DOCUMENT, setProperty(int, Object), Constant Field Values

DOCUMENT_URI_PASS

public static final int DOCUMENT_URI_PASS
A string value constant for PROPERTY_XML_PARSER_DOCUMENT_URI
See Also:
Constant Field Values

DOCUMENT_URI_HIDE

public static final int DOCUMENT_URI_HIDE
A string value constant for PROPERTY_XML_PARSER_DOCUMENT_URI
See Also:
Constant Field Values

DOCUMENT_URI_PASS_URL

public static final int DOCUMENT_URI_PASS_URL
A string value constant for PROPERTY_XML_PARSER_DOCUMENT_URI
See Also:
Constant Field Values

Constructor Detail

OXQEntity

public OXQEntity(java.lang.Object data)
Constructs an entity.
Parameters:
data - The entity.

OXQEntity

public OXQEntity(java.lang.Object data,
                 java.lang.String mediaType)
Constructs an entity.
Parameters:
data - The entity.
mediaType - Media-Type of the entity

Method Detail

setData

public void setData(java.lang.Object data)
Sets the entity.
Parameters:
data - the entity

getData

public java.lang.Object getData()
Returns the entity.
Returns:
the entity

setMediaType

public void setMediaType(java.lang.String mediaType)
Sets the Media-Type of the entity.
Parameters:
mediaType - the Media-Type

getMediaType

public java.lang.String getMediaType()
Returns the Media-Type of the entity
Returns:
the Media-Type

setProperty

public void setProperty(int key,
                        java.lang.Object value)
Sets additional processing options for this entity.
Parameters:
key - the property key
value - the property value

getProperty

public java.lang.Object getProperty(int key)
Returns the property value for the given property key.
Returns:
the property value

clone

public OXQEntity clone()
Standard override; no change in semantics.
Overrides:
clone in class java.lang.Object

enlistCloseable

public void enlistCloseable(java.io.Closeable closeable)
Description copied from interface: OXQCloseable
Declares a closeable object that will be closed when this object is closed.
Specified by:
enlistCloseable in interface OXQCloseable
Parameters:
closeable - input streaming object that close() must be invoked on after close() is invoked on this object.
See Also:
Detailed description

enlistCloseable

public void enlistCloseable(javax.xml.stream.XMLStreamReader closeable)
Description copied from interface: OXQCloseable
Declares an XMLStreamReader object that will be closed when this object is closed.

Note: XMLStreamReader implementations don't usually conform to the thread-safety semantics defined above, so their use as resources is not recommended in multi-threaded environments.

Specified by:
enlistCloseable in interface OXQCloseable
Parameters:
closeable - object that close() must be invoked on after close() is invoked on this object.
See Also:
Detailed description

enlistCloseable

public void enlistCloseable(XQSequence closeable)
Description copied from interface: OXQCloseable
Declares an XQSequence object that will be closed when this object is closed.
Specified by:
enlistCloseable in interface OXQCloseable
Parameters:
closeable - object that close() must be invoked on after close() is invoked on this object.
See Also:
Detailed description

getEnlistedCloseables

public java.lang.Object[] getEnlistedCloseables()
Returns closeable resources associated with this entity.
Returns:
array of closeable resources or null if no resources have been registered

Skip navigation links

Oracle® Database XML Java API Reference
12c Release 1 (12.1)

E15981-09


Copyright © 2003, 2014, Oracle and/or its affiliates. All rights reserved.