KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > net > sf > saxon > om > ExternalObjectModel


1 package net.sf.saxon.om;
2
3 import net.sf.saxon.Configuration;
4 import net.sf.saxon.event.Receiver;
5 import net.sf.saxon.event.PipelineConfiguration;
6 import net.sf.saxon.expr.XPathContext;
7 import net.sf.saxon.trans.XPathException;
8 import net.sf.saxon.value.Value;
9 import net.sf.saxon.value.SequenceExtent;
10
11 import javax.xml.transform.Result JavaDoc;
12 import javax.xml.transform.Source JavaDoc;
13
14 /**
15  * This interface must be implemented by any third-party object model that can
16  * be wrapped with a wrapper that implements the Saxon Object Model (the NodeInfo interface).
17  * <p>
18  * This interface is designed to enable advanced applications to implement and register
19  * new object model implementations that Saxon can then use without change. Although it is intended
20  * for external use, it cannot at this stage be considered part of the stable Saxon Public API.
21  * In particular, it is likely that the interface will grow by the addition of new methods.
22  */

23
24 public interface ExternalObjectModel {
25
26     /**
27      * Test whether this object model recognizes a given node as one of its own. This method
28      * will generally be called at run time.
29      * @param object An object that possibly represents a node
30      * @return true if the object is a representation of a node in this object model
31      */

32
33     public boolean isRecognizedNode(Object JavaDoc object);
34
35     /**
36      * Test whether this object model recognizes a given class as representing a
37      * node in that object model. This method will generally be called at compile time.
38      * @param nodeClass A class that possibly represents nodes
39      * @return true if the class is used to represent nodes in this object model
40      */

41
42     public boolean isRecognizedNodeClass(Class JavaDoc nodeClass);
43
44     /**
45      * Test whether this object model recognizes a given class as representing a
46      * list of nodes in that object model. This method will generally be called at compile time.
47      * @param nodeClass A class that possibly represents nodes
48      * @return true if the class is used to represent nodes in this object model
49      */

50
51     public boolean isRecognizedNodeListClass(Class JavaDoc nodeClass);
52
53     /**
54      * Test whether this object model recognizes a particular kind of JAXP Result object,
55      * and if it does, return a Receiver that builds an instance of this data model from
56      * a sequence of events. If the Result is not recognised, return null.
57      */

58
59     public Receiver getDocumentBuilder(Result JavaDoc result) throws XPathException;
60
61     /**
62      * Test whether this object model recognizes a particular kind of JAXP Source object,
63      * and if it does, send the contents of the document to a supplied Receiver, and return true.
64      * Otherwise, return false.
65      */

66
67     public boolean sendSource(Source JavaDoc source, Receiver receiver, PipelineConfiguration pipe) throws XPathException;
68
69     /**
70      * Wrap or unwrap a node using this object model to return the corresponding Saxon node. If the supplied
71      * source does not belong to this object model, return null
72      */

73
74     public NodeInfo unravel(Source JavaDoc source, Configuration config);
75
76     /**
77      * Convert a Java object to an XPath value. If the supplied object is recognized as a representation
78      * of a value using this object model, the object model should convert the value to an XPath value
79      * and return this as the result. If not, it should return null. If the object is recognized but cannot
80      * be converted, an exception should be thrown
81      */

82
83     public Value convertObjectToXPathValue(Object JavaDoc object, Configuration config) throws XPathException;
84
85     /**
86      * Convert an XPath value to an object in this object model. If the supplied value can be converted
87      * to an object in this model, of the specified class, then the conversion should be done and the
88      * resulting object returned. If the value cannot be converted, the method should return null. Note
89      * that the supplied class might be a List, in which case the method should inspect the contents of the
90      * Value to see whether they belong to this object model.
91      * @throws XPathException if the target class is explicitly associated with this object model, but the
92      * supplied value cannot be converted to the appropriate class
93      */

94
95     public Object JavaDoc convertXPathValueToObject(Value value, Class JavaDoc targetClass, XPathContext context) throws XPathException;
96
97     /**
98      * Wrap a document node in the external object model in a document wrapper that implements
99      * the Saxon DocumentInfo interface
100      * @param node a node (any node) in the third party document
101      * @param baseURI the base URI of the node (supply "" if unknown)
102      * @param config the Saxon configuration (which among other things provides access to the NamePool)
103      * @return the wrapper, which must implement DocumentInfo
104      */

105
106     public DocumentInfo wrapDocument(Object JavaDoc node, String JavaDoc baseURI, Configuration config);
107
108     /**
109      * Wrap a node within the external object model in a node wrapper that implements the Saxon
110      * VirtualNode interface (which is an extension of NodeInfo)
111      * @param document the document wrapper, as a DocumentInfo object
112      * @param node the node to be wrapped. This must be a node within the document wrapped by the
113      * DocumentInfo provided in the first argument
114      * @return the wrapper for the node, as an instance of VirtualNode
115      */

116
117     public NodeInfo wrapNode(DocumentInfo document, Object JavaDoc node);
118
119     /**
120      * Convert a sequence of values to a NODELIST, as defined in the JAXP XPath API spec. This method
121      * is used when the evaluate() request specifies the return type as NODELIST, regardless of the
122      * actual results of the expression. If the sequence contains things other than nodes, the fallback
123      * is to return the sequence as a Java List object. The method can return null to invoke fallback
124      * behaviour.
125      */

126
127     public Object JavaDoc convertToNodeList(SequenceExtent extent);
128 }
129
130
131 //
132
// The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
133
// you may not use this file except in compliance with the License. You may obtain a copy of the
134
// License at http://www.mozilla.org/MPL/
135
//
136
// Software distributed under the License is distributed on an "AS IS" basis,
137
// WITHOUT WARRANTY OF ANY KIND, either express or implied.
138
// See the License for the specific language governing rights and limitations under the License.
139
//
140
// The Original Code is: all this file.
141
//
142
// The Initial Developer of the Original Code is Michael H. Kay.
143
//
144
// Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
145
//
146
// Contributor(s): Gunther Schadow (changes to allow access to public fields; also wrapping
147
// of extensions and mapping of null to empty sequence).
148
//
149
Popular Tags