| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| package org.apache.uima.util; |
| |
| import java.net.URL; |
| |
| import org.apache.uima.analysis_engine.AnalysisEngineDescription; |
| import org.apache.uima.analysis_engine.ResultSpecification; |
| import org.apache.uima.analysis_engine.TaeDescription; |
| import org.apache.uima.collection.CasConsumerDescription; |
| import org.apache.uima.collection.CasInitializerDescription; |
| import org.apache.uima.collection.CollectionReaderDescription; |
| import org.apache.uima.collection.metadata.CpeDescription; |
| import org.apache.uima.flow.FlowControllerDescription; |
| import org.apache.uima.resource.CustomResourceSpecifier; |
| import org.apache.uima.resource.PearSpecifier; |
| import org.apache.uima.resource.ResourceSpecifier; |
| import org.apache.uima.resource.URISpecifier; |
| import org.apache.uima.resource.metadata.FsIndexCollection; |
| import org.apache.uima.resource.metadata.ResourceManagerConfiguration; |
| import org.apache.uima.resource.metadata.ResourceMetaData; |
| import org.apache.uima.resource.metadata.TypePriorities; |
| import org.apache.uima.resource.metadata.TypeSystemDescription; |
| import org.apache.uima.search.IndexBuildSpecification; |
| import org.w3c.dom.Element; |
| |
| /** |
| * A UIMA <code>XMLParser</code> parses XML documents and generates UIMA components represented by |
| * the XML. |
| * <p> |
| * An application obtains a reference to the <code>XMLParser</code> by calling the |
| * {@link org.apache.uima.UIMAFramework#getXMLParser()} method. The application then uses the |
| * <code>XMLParser</code> by passing an <code>InputStream</code> to one of its |
| * <code>parse</code> methods - for example |
| * {@link #parseAnalysisEngineDescription(XMLInputSource)} for parsing an |
| * {@link AnalysisEngineDescription} from its XML representation. |
| * <p> |
| * XML schema validation is off by default; it can be turned on by calling the method |
| * {@link #enableSchemaValidation(boolean)}. |
| * <p> |
| * UIMA developers who provide new types of XMLizable components must configure the XML parser by |
| * using the {@link #addMapping(String,String)} method to specify mappings between XML Element names |
| * and the class names of the objects to be built from elements with those names. All objects to be |
| * built by the XML parser must implement {@link XMLizable} and provide an implementation of |
| * {@link XMLizable#buildFromXMLElement(Element,XmlParserBak)}. |
| * <p> |
| * Note that we are considering replacing this ad-hoc XML data binding interface with the java |
| * standard extension JAXB. See <a href="http://java.sun.com/xml/jaxb"> http://java.sun.com/xml/jaxb</a> |
| * for details on JAXB. |
| * |
| * |
| */ |
| public interface XMLParser { |
| |
| /** |
| * Enables or disables XML scheam validation. |
| * |
| * @param aEnable |
| * true to enable validation, false to disable validation |
| */ |
| public void enableSchemaValidation(boolean aEnable); |
| |
| /** |
| * Parses an XML input stream and produces an object. elements. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aNamespaceForSchema |
| * XML namespace for elements to be validated against XML schema. If null, no schema will |
| * be used (unless one is declared in the document itself). This parameter is ignored if |
| * schema validation has not been enabled via {@link #enableSchemaValidation(boolean)}. |
| * @param aSchemaUrl |
| * URL to XML schema that will be used to validate the XML document. If null, no schema |
| * will be used (unless one is declared in the document itself). This parameter is |
| * ignored if schema validation has not been enabled via |
| * {@link #enableSchemaValidation(boolean)}. |
| * |
| * @return an <code>XMLizable</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid object |
| */ |
| public XMLizable parse(XMLInputSource aInput, String aNamespaceForSchema, URL aSchemaUrl) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses an XML input stream and produces an object. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aNamespaceForSchema |
| * XML namespace for elements to be validated against XML schema. If null, no schema will |
| * be used (unless one is declared in the document itself). This parameter is ignored if |
| * schema validation has not been enabled via {@link #enableSchemaValidation(boolean)}. |
| * @param aSchemaUrl |
| * URL to XML schema that will be used to validate the XML document. If null, no schema |
| * will be used (unless one is declared in the document itself). This parameter is |
| * ignored if schema validation has not been enabled via |
| * {@link #enableSchemaValidation(boolean)}. |
| * @param aOptions |
| * option settings |
| * |
| * @return an <code>XMLizable</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid object |
| */ |
| public XMLizable parse(XMLInputSource aInput, String aNamespaceForSchema, URL aSchemaUrl, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses an XML input stream and produces an object. XIncludes will be expanded but no schema |
| * validation will be done. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return an <code>XMLizable</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid object |
| */ |
| public XMLizable parse(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses an XML input stream and produces an object. No schema validation will be done. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return an <code>XMLizable</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid object |
| */ |
| public XMLizable parse(XMLInputSource aInput, ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a ResourceSpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>ResourceSpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid ResourceSpecifier |
| */ |
| public ResourceSpecifier parseResourceSpecifier(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses a ResourceSpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>ResourceSpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid ResourceSpecifier |
| */ |
| public ResourceSpecifier parseResourceSpecifier(XMLInputSource aInput, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a ResourceMetaData object from an XML input stream. XML schema validation will be done |
| * against the {@link #RESOURCE_SPECIFIER_SCHEMA_NAME} if it can be found in the classpath. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>ResourceMetaData</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid ResourceSpecifier |
| */ |
| public ResourceMetaData parseResourceMetaData(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses a ResourceMetaData object from an XML input stream. XML schema validation will be done |
| * against the {@link #RESOURCE_SPECIFIER_SCHEMA_NAME} if it can be found in the classpath. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>ResourceMetaData</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid ResourceSpecifier |
| */ |
| public ResourceMetaData parseResourceMetaData(XMLInputSource aInput, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a URISpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>URISpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid URISpecifier |
| */ |
| public URISpecifier parseURISpecifier(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses a URISpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>URISpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid URISpecifier |
| */ |
| public URISpecifier parseURISpecifier(XMLInputSource aInput, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses an AnalysisEngineDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return an <code>AnalysisEngineDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid AnalysisEngineDescription |
| */ |
| public AnalysisEngineDescription parseAnalysisEngineDescription(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses an AnalysisEngineDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return an <code>AnalysisEngineDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid AnalysisEngineDescription |
| */ |
| public AnalysisEngineDescription parseAnalysisEngineDescription(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a TaeDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>TaeDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid TaeDescription |
| * |
| * @deprecated As of v2.0, {@link #parseAnalysisEngineDescription(XMLInputSource)} should be used |
| * instead. |
| */ |
| public TaeDescription parseTaeDescription(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses a TaeDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>TaeDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid TaeDescription |
| * |
| * @deprecated As of v2.0, {@link #parseAnalysisEngineDescription(XMLInputSource,ParsingOptions)} |
| * should be used instead. |
| */ |
| public TaeDescription parseTaeDescription(XMLInputSource aInput, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a CasConsumerDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>CasConsumerDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CasConsumerDescription |
| */ |
| public CasConsumerDescription parseCasConsumerDescription(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a CasConsumerDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>CasConsumerDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CasConsumerDescription |
| */ |
| public CasConsumerDescription parseCasConsumerDescription(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a CasInitializerDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>CasInitializerDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CasInitializerDescription |
| */ |
| public CasInitializerDescription parseCasInitializerDescription(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a CasInitializerDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>CasInitializerDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CasInitializerDescription |
| */ |
| public CasInitializerDescription parseCasInitializerDescription(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a CollectionReaderDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>CollectionReaderDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CollectionReaderDescription |
| */ |
| public CollectionReaderDescription parseCollectionReaderDescription(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a CollectionReaderDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>CollectionReaderDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CollectionReaderDescription |
| */ |
| public CollectionReaderDescription parseCollectionReaderDescription(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a CpeDescription from an XML input stream. |
| * <p> |
| * NOTE: the option settings {@link ParsingOptions} are not currently available for parsing |
| * CpeDescriptions, because they use a different parsing mechanism than the other specifier types. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>cpeDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid IndexingSpecification |
| */ |
| public CpeDescription parseCpeDescription(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses a ResultSpecification from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>ResultSpecification</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid ResultSpecification |
| */ |
| public ResultSpecification parseResultSpecification(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a ResultSpecification from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>ResultSpecification</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid ResultSpecification |
| */ |
| public ResultSpecification parseResultSpecification(XMLInputSource aInput, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a TypeSystemDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>TypeSystemDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid TypeSystemDescription |
| */ |
| public TypeSystemDescription parseTypeSystemDescription(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a TypeSystemDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>TypeSystemDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid TypeSystemDescription |
| */ |
| public TypeSystemDescription parseTypeSystemDescription(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a TypePriorities declaration from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>TypePriorities</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid TypePriorities |
| */ |
| public TypePriorities parseTypePriorities(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses a TypePriorities declaration from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>TypePriorities</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid TypePriorities |
| */ |
| public TypePriorities parseTypePriorities(XMLInputSource aInput, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a FsIndexCollection from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>FsIndexCollection</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid FsIndexCollection |
| */ |
| public FsIndexCollection parseFsIndexCollection(XMLInputSource aInput) throws InvalidXMLException; |
| |
| /** |
| * Parses a FsIndexCollection from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>FsIndexCollection</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid FsIndexCollection |
| */ |
| public FsIndexCollection parseFsIndexCollection(XMLInputSource aInput, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a ResourceManagerConfiguration from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>ResourceManagerConfiguration</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid |
| * ResourceManagerConfiguration |
| */ |
| public ResourceManagerConfiguration parseResourceManagerConfiguration(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a ResourceManagerConfiguration from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>ResourceManagerConfiguration</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid |
| * ResourceManagerConfiguration |
| */ |
| public ResourceManagerConfiguration parseResourceManagerConfiguration(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a FlowControllerDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>FlowControllerDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid FlowControllerDescription |
| */ |
| public FlowControllerDescription parseFlowControllerDescription(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a FlowControllerDescription from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>FlowControllerDescription</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid FlowControllerDescription |
| */ |
| public FlowControllerDescription parseFlowControllerDescription(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a CustomResourceSpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>CustomResourceSpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CustomResourceSpecifier |
| */ |
| public CustomResourceSpecifier parseCustomResourceSpecifier(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a CustomResourceSpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>CustomResourceSpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid CustomResourceSpecifier |
| */ |
| public CustomResourceSpecifier parseCustomResourceSpecifier(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses a PearSpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return a <code>PearSpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid PearSpecifier |
| */ |
| public PearSpecifier parsePearSpecifier(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses a PearSpecifier from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return a <code>PearSpecifier</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid PearSpecifier |
| */ |
| public PearSpecifier parsePearSpecifier(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Parses an IndexBuildSpecification from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * |
| * @return an <code>IndexBuildSpecification</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid IndexBuildSpecification |
| */ |
| public IndexBuildSpecification parseIndexBuildSpecification(XMLInputSource aInput) |
| throws InvalidXMLException; |
| |
| /** |
| * Parses an IndexBuildSpecification from an XML input stream. |
| * |
| * @param aInput |
| * the input source from which to read the XML document |
| * @param aOptions |
| * option settings |
| * |
| * @return an <code>IndexBuildSpecification</code> object constructed from the XML document |
| * |
| * @throws InvalidXMLException |
| * if the input XML is not valid or does not specify a valid IndexBuildSpecification |
| */ |
| public IndexBuildSpecification parseIndexBuildSpecification(XMLInputSource aInput, |
| ParsingOptions aOptions) throws InvalidXMLException; |
| |
| /** |
| * Builds an object from its XML DOM representation. This method is not typically called by |
| * applications. It may be called from within a |
| * {@link XMLizable#buildFromXMLElement(Element,XmlParserBak)} method to construct sub-objects. |
| * |
| * @param aElement |
| * a DOM Element |
| * |
| * @return an <code>XMLizable</code> object constructed from the DOM element |
| * |
| * @throws InvalidXMLException |
| * if the XML element does not specify a valid object |
| */ |
| public XMLizable buildObject(Element aElement) throws InvalidXMLException; |
| |
| /** |
| * Builds an object from its XML DOM representation. This method is not typically called by |
| * applications. It may be called from within a |
| * {@link XMLizable#buildFromXMLElement(Element,XmlParserBak)} method to construct sub-objects. |
| * |
| * @param aElement |
| * a DOM Element |
| * @param aOptions |
| * option settings |
| * |
| * @return an <code>XMLizable</code> object constructed from the DOM element |
| * |
| * @throws InvalidXMLException |
| * if the XML element does not specify a valid object |
| */ |
| public XMLizable buildObject(Element aElement, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Builds an object from its XML DOM representation. This method is not typically called by |
| * applications. It may be called from within a |
| * {@link XMLizable#buildFromXMLElement(Element,XmlParser)} method to construct sub-objects. |
| * <p> |
| * This method is similar to {@link #buildObject(Element, XMLParser.ParsingOptions)} but can also |
| * parse primitive-typed objects wrapped as XML elements, such as |
| * <code><integer>42</integer</code>. |
| * |
| * @param aElement |
| * a DOM Element |
| * @param aOptions |
| * option settings |
| * |
| * @return an object constructed from the DOM element. This can be either an instance of |
| * {@link Xmlizable}, {@link String}, or one of the primitive type wrapper objects (e.g. |
| * {@link Integer}, {@link Float}, {@link Boolean}). |
| * |
| * @throws InvalidXMLException |
| * if the XML element does not specify a valid object |
| */ |
| public Object buildObjectOrPrimitive(Element aElement, ParsingOptions aOptions) |
| throws InvalidXMLException; |
| |
| /** |
| * Creates a new <code>SaxDeserializer</code> object, which implements the SAX |
| * {@link org.xml.sax.ContentHandler} interface and can be used to deserialize an |
| * {@link XMLizable} object from the events sent from a SAX parser. This can be used if the |
| * application already has a SAX parser that generates these events. In most cases, it is easier |
| * to use one of the <code>parse</code> methods on this interface. |
| * <p> |
| * The SAX deserializer returned my this method will expand XIncludes but will not do schema |
| * validation. |
| * |
| * @return an object that implements {@link org.xml.sax.ContentHandler} and can be used to |
| * deserialize an {@link XMLizable} object from SAX events. |
| * |
| * @throws InvalidXMLException |
| * if the XML element does not specify a valid object |
| */ |
| public SaxDeserializer newSaxDeserializer(); |
| |
| /** |
| * Creates a new <code>SaxDeserializer</code>. |
| * |
| * @param aOptions |
| * option settings |
| * |
| * @return an object that implements {@link org.xml.sax.ContentHandler} and can be used to |
| * deserialize an {@link XMLizable} object from SAX events. |
| * |
| * @throws InvalidXMLException |
| * if the XML element does not specify a valid object |
| * @see #newSaxDeserializer() |
| * |
| */ |
| public SaxDeserializer newSaxDeserializer(ParsingOptions aOptions); |
| |
| /** |
| * Configures this XMLParser by registering a mapping between the name of an XML element and the |
| * Class of object to be built from elements with that name. |
| * |
| * @param aElementName |
| * the name of an XML element |
| * @param aClassName |
| * the name of a Class of object to be built. This class must implement {@link XMLizable} |
| * and have a zero-argument constructor. |
| * |
| * @throws ClassNotFoundException |
| * if the class named by <code>aClassName</code> could not be found |
| */ |
| public void addMapping(String aElementName, String aClassName) throws ClassNotFoundException; |
| |
| /** |
| * XML namespace for ResourceSpecifiers. XML ResourceSpecifier documents must use this namespace |
| * or they will be considered invalid by the schema validator. |
| */ |
| public static final String RESOURCE_SPECIFIER_NAMESPACE = "http://uima.apache.org/resourceSpecifier"; |
| |
| /** |
| * Name of schema for ResourceSpecifiers. This file will be looked up in the classpath. |
| */ |
| public static final String RESOURCE_SPECIFIER_SCHEMA_NAME = "/resourceSpecifierSchema.xsd"; |
| |
| /** |
| * Option settings for the parser. |
| * |
| * |
| */ |
| public static class ParsingOptions { |
| /** |
| * Whether to expand <xi:include> elements according to the XInclude spec. |
| * |
| * @deprecated XInclude is no longer supported |
| */ |
| public boolean expandXIncludes; |
| |
| /** |
| * Whether to expand <envVarRef>VARNAME</envVarRef> elements by substituting the |
| * value of the System proprery VARNAME. |
| */ |
| public boolean expandEnvVarRefs; |
| |
| /** |
| * Creates a new ParsingOptions object. |
| * |
| * @param aExpandXIncludes |
| * Whether to expand <xi:include> elements according to the XInclude spec. |
| * @param aExpandEnvVarRefs |
| * Whether to expand <envVarRef>VARNAME</envVarRef> elements by |
| * substituting the value of the System proprery VARNAME. |
| * @deprecated XInclude is no longer supported |
| */ |
| public ParsingOptions(boolean aExpandXIncludes, boolean aExpandEnvVarRefs) { |
| expandXIncludes = aExpandXIncludes; |
| expandEnvVarRefs = aExpandEnvVarRefs; |
| } |
| |
| /** |
| * Creates a new ParsingOptions object. |
| * |
| * @param aExpandEnvVarRefs |
| * Whether to expand <envVarRef>VARNAME</envVarRef> elements by |
| * substituting the value of the System proprery VARNAME. |
| */ |
| public ParsingOptions(boolean aExpandEnvVarRefs) { |
| expandEnvVarRefs = aExpandEnvVarRefs; |
| } |
| } |
| } |
