001: package net.sf.saxon.om;
002:
003: import net.sf.saxon.Configuration;
004: import net.sf.saxon.event.Receiver;
005: import net.sf.saxon.event.PipelineConfiguration;
006: import net.sf.saxon.expr.XPathContext;
007: import net.sf.saxon.trans.XPathException;
008: import net.sf.saxon.value.Value;
009: import net.sf.saxon.value.SequenceExtent;
010:
011: import javax.xml.transform.Result;
012: import javax.xml.transform.Source;
013:
014: /**
015: * This interface must be implemented by any third-party object model that can
016: * be wrapped with a wrapper that implements the Saxon Object Model (the NodeInfo interface).
017: * <p>
018: * This interface is designed to enable advanced applications to implement and register
019: * new object model implementations that Saxon can then use without change. Although it is intended
020: * for external use, it cannot at this stage be considered part of the stable Saxon Public API.
021: * In particular, it is likely that the interface will grow by the addition of new methods.
022: */
023:
024: public interface ExternalObjectModel {
025:
026: /**
027: * Test whether this object model recognizes a given node as one of its own. This method
028: * will generally be called at run time.
029: * @param object An object that possibly represents a node
030: * @return true if the object is a representation of a node in this object model
031: */
032:
033: public boolean isRecognizedNode(Object object);
034:
035: /**
036: * Test whether this object model recognizes a given class as representing a
037: * node in that object model. This method will generally be called at compile time.
038: * @param nodeClass A class that possibly represents nodes
039: * @return true if the class is used to represent nodes in this object model
040: */
041:
042: public boolean isRecognizedNodeClass(Class nodeClass);
043:
044: /**
045: * Test whether this object model recognizes a given class as representing a
046: * list of nodes in that object model. This method will generally be called at compile time.
047: * @param nodeClass A class that possibly represents nodes
048: * @return true if the class is used to represent nodes in this object model
049: */
050:
051: public boolean isRecognizedNodeListClass(Class nodeClass);
052:
053: /**
054: * Test whether this object model recognizes a particular kind of JAXP Result object,
055: * and if it does, return a Receiver that builds an instance of this data model from
056: * a sequence of events. If the Result is not recognised, return null.
057: */
058:
059: public Receiver getDocumentBuilder(Result result)
060: throws XPathException;
061:
062: /**
063: * Test whether this object model recognizes a particular kind of JAXP Source object,
064: * and if it does, send the contents of the document to a supplied Receiver, and return true.
065: * Otherwise, return false.
066: */
067:
068: public boolean sendSource(Source source, Receiver receiver,
069: PipelineConfiguration pipe) throws XPathException;
070:
071: /**
072: * Wrap or unwrap a node using this object model to return the corresponding Saxon node. If the supplied
073: * source does not belong to this object model, return null
074: */
075:
076: public NodeInfo unravel(Source source, Configuration config);
077:
078: /**
079: * Convert a Java object to an XPath value. If the supplied object is recognized as a representation
080: * of a value using this object model, the object model should convert the value to an XPath value
081: * and return this as the result. If not, it should return null. If the object is recognized but cannot
082: * be converted, an exception should be thrown
083: */
084:
085: public Value convertObjectToXPathValue(Object object,
086: Configuration config) throws XPathException;
087:
088: /**
089: * Convert an XPath value to an object in this object model. If the supplied value can be converted
090: * to an object in this model, of the specified class, then the conversion should be done and the
091: * resulting object returned. If the value cannot be converted, the method should return null. Note
092: * that the supplied class might be a List, in which case the method should inspect the contents of the
093: * Value to see whether they belong to this object model.
094: * @throws XPathException if the target class is explicitly associated with this object model, but the
095: * supplied value cannot be converted to the appropriate class
096: */
097:
098: public Object convertXPathValueToObject(Value value,
099: Class targetClass, XPathContext context)
100: throws XPathException;
101:
102: /**
103: * Wrap a document node in the external object model in a document wrapper that implements
104: * the Saxon DocumentInfo interface
105: * @param node a node (any node) in the third party document
106: * @param baseURI the base URI of the node (supply "" if unknown)
107: * @param config the Saxon configuration (which among other things provides access to the NamePool)
108: * @return the wrapper, which must implement DocumentInfo
109: */
110:
111: public DocumentInfo wrapDocument(Object node, String baseURI,
112: Configuration config);
113:
114: /**
115: * Wrap a node within the external object model in a node wrapper that implements the Saxon
116: * VirtualNode interface (which is an extension of NodeInfo)
117: * @param document the document wrapper, as a DocumentInfo object
118: * @param node the node to be wrapped. This must be a node within the document wrapped by the
119: * DocumentInfo provided in the first argument
120: * @return the wrapper for the node, as an instance of VirtualNode
121: */
122:
123: public NodeInfo wrapNode(DocumentInfo document, Object node);
124:
125: /**
126: * Convert a sequence of values to a NODELIST, as defined in the JAXP XPath API spec. This method
127: * is used when the evaluate() request specifies the return type as NODELIST, regardless of the
128: * actual results of the expression. If the sequence contains things other than nodes, the fallback
129: * is to return the sequence as a Java List object. The method can return null to invoke fallback
130: * behaviour.
131: */
132:
133: public Object convertToNodeList(SequenceExtent extent);
134: }
135:
136: //
137: // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
138: // you may not use this file except in compliance with the License. You may obtain a copy of the
139: // License at http://www.mozilla.org/MPL/
140: //
141: // Software distributed under the License is distributed on an "AS IS" basis,
142: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
143: // See the License for the specific language governing rights and limitations under the License.
144: //
145: // The Original Code is: all this file.
146: //
147: // The Initial Developer of the Original Code is Michael H. Kay.
148: //
149: // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
150: //
151: // Contributor(s): Gunther Schadow (changes to allow access to public fields; also wrapping
152: // of extensions and mapping of null to empty sequence).
153: //
|