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  ;
12  import javax.xml.transform.Source  ;
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   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   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   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   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   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   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   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   convertXPathValueToObject(Value value, Class   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   node, String   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags