Interface XMLUtilAccess

All Known Subinterfaces:
AuthorXMLUtilAccess

@API(type=NOT_EXTENDABLE, src=PUBLIC) public interface XMLUtilAccess
XML Utilities
Since:
11.2
  • Field Details

    • TRANSFORMER_XALAN

      static final int TRANSFORMER_XALAN
      Xalan transformer
      See Also:
    • TRANSFORMER_SAXON_6

      static final int TRANSFORMER_SAXON_6
      Saxon 6 transformer
      See Also:
    • TRANSFORMER_SAXON_HOME_EDITION

      static final int TRANSFORMER_SAXON_HOME_EDITION
      Saxon 9 Home Edition transformer type (no extensions support).
      See Also:
    • TRANSFORMER_SAXON_PROFESSIONAL_EDITION

      @Deprecated static final int TRANSFORMER_SAXON_PROFESSIONAL_EDITION
      Deprecated.
      Since Oxygen 23 you can no longer create Saxon 9 PE transformers using this constant. The created transformer will be a Saxon HE transformer instead.
      Saxon 9 Professional Edition transformer type (full extensions support).
      See Also:
    • TRANSFORMER_SAXON_ENTERPRISE_EDITION

      @Deprecated static final int TRANSFORMER_SAXON_ENTERPRISE_EDITION
      Deprecated.
      Since Oxygen 23 you can no longer create Saxon 9 PE transformers using this constant. The created transformer will be a Saxon HE transformer instead.
      Saxon 9 Enterprise Edition transformer type (full extensions support + schema aware).
      See Also:
    • EXTENSION_PREFIX

      static final String EXTENSION_PREFIX
      Predefined prefix for XPath extension function.
      See Also:
    • EXTENSION_NS

      static final String EXTENSION_NS
      Namespace for XPath extension functions.
      See Also:
  • Method Details

    • createXSLTTransformer

      Transformer createXSLTTransformer(Source styleSource, URL[] extensionJars, int transformerType) throws TransformerConfigurationException
      Create a new XSLT transformer. The options set in the oXygen preferences are used.
      Parameters:
      styleSource - The source XSL
      extensionJars - Jars with extension libraries which can be used by the transformer, can be null
      transformerType - The type of the transformer to create, one of the constants defined in this class starting with TRANSFORMER_
      Returns:
      The new transformer.
      Throws:
      TransformerConfigurationException - An Exception is thrown if an error occurs during parsing of the source.
    • createSaxon9XSLTTransformerWithExtensions

      Transformer createSaxon9XSLTTransformerWithExtensions(Source styleSource, net.sf.saxon.lib.ExtensionFunctionDefinition[] extensionFunctions, int transformerType) throws TransformerConfigurationException

      Create a Saxon 9 Home Edition transformer with the specified extension functions.

      Parameters:
      styleSource - The source XSL
      extensionFunctions - Jars with extension libraries which can be used by the transformer, can be null
      transformerType - The type of the transformer to create can only be TRANSFORMER_SAXON_HOME_EDITION.
      Returns:
      The new transformer.
      Throws:
      TransformerConfigurationException - An Exception is thrown if an error occurs during parsing of the source.
    • createXSLTTransformer

      Transformer createXSLTTransformer(Source styleSource, URL[] extensionJars, int transformerType, boolean useOxygenOptions) throws TransformerConfigurationException
      Create a new XSLT transformer.
      Parameters:
      styleSource - The source XSL
      extensionJars - Jars with extension libraries which can be used by the transformer. Can be null.
      transformerType - The type of the transformer to create, one of the constants defined in this class starting with TRANSFORMER_
      useOxygenOptions - If true the options set in the oXygen preferences are used. Otherwise no options are set to the transformers.
      Returns:
      The new transformer.
      Throws:
      TransformerConfigurationException - An Exception is thrown if an error occurs during parsing of the source.
      Since:
      12.2
    • createSaxon9HEXSLTTransformerWithExtensions

      Transformer createSaxon9HEXSLTTransformerWithExtensions(Source styleSource, net.sf.saxon.lib.ExtensionFunctionDefinition[] saxonExtensions) throws TransformerConfigurationException

      Create a Saxon 9 Home Edition transformer with the specified extension functions. This is necessary when the extension functions cannot be called by reflection because there is no license for the commercial version of Saxon 9.

      The Saxon 9 options set in the oXygen preferences are not used.

      Parameters:
      styleSource - The source XSL
      saxonExtensions - The list of Saxon 9 extensions.
      Returns:
      The new transformer.
      Throws:
      TransformerConfigurationException - An Exception is thrown if an error occurs during parsing of the source.
      Since:
      12.2
    • createXQueryTransformer

      Transformer createXQueryTransformer(Source xquerySource, URL[] extensionJars, int transformerType) throws TransformerConfigurationException
      Create a new XQuery transformer. The options set in the oXygen preferences are used.
      Parameters:
      xquerySource - The source XQuery file
      extensionJars - Jars with extension libraries which can be used by the transformer, can be null
      transformerType - The type of the transformer to create, can only be TRANSFORMER_SAXON_HOME_EDITION
      Returns:
      The new transformer.
      Throws:
      TransformerConfigurationException - An Exception is thrown if an error occurs during parsing of the source.
    • createXQueryTransformer

      Transformer createXQueryTransformer(Source xquerySource, URL[] extensionJars, int transformerType, boolean useOxygenOptions) throws TransformerConfigurationException
      Create a new XQuery transformer.
      Parameters:
      xquerySource - The source XQuery file
      extensionJars - Jars with extension libraries which can be used by the transformer. Can be null.
      transformerType - The type of the transformer to create, can only be TRANSFORMER_SAXON_HOME_EDITION
      useOxygenOptions - If true the options set in the oXygen preferences are used. Otherwise no options are set to the transformers.
      Returns:
      The new transformer.
      Throws:
      TransformerConfigurationException - An Exception is thrown if an error occurs during parsing of the source.
      Since:
      12.2
    • resetXMLCatalogs

      void resetXMLCatalogs()
      Reset the loaded XML catalogs. This way next time the catalogs are needed they will first be rebuilt.
    • resolvePathThroughCatalogs

      URL resolvePathThroughCatalogs(URL baseURL, String relativeLocation, boolean entityResolve, boolean uriResolve)
      Try to resolve a relative location to an absolute path by using the XML catalogs.
      Parameters:
      baseURL - The URL of the current opened XML file.
      relativeLocation - The relative location to be resolved.
      entityResolve - true if the catalog entity resolver should be used.
      uriResolve - true if the catalog URI resolver should be used.
      Returns:
      The absolute URL. It returns null only for URLs with unknown protocols for which an URL object cannot be constructed.
    • escapeAttributeValue

      String escapeAttributeValue(String attributeValue)
      Escape an attribute value so that the XML document remains well-formed.
      Parameters:
      attributeValue - The attribute value.
      Returns:
      The escaped value. It does not return null.
    • escapeTextValue

      String escapeTextValue(String textValue)
      Escape text which will be inserted in the XML so that the XML document remains well-formed.
      Parameters:
      textValue - The text value.
      Returns:
      The escaped value. It does not return null.
      Since:
      18
    • unescapeAttributeValue

      String unescapeAttributeValue(String attributeValue)
      Unescape an attribute value.
      Parameters:
      attributeValue - The attribute value to be unescaped.
      Returns:
      The unescaped value. It does not return null.
      Throws:
      IllegalArgumentException - when having problems with unescaping hex or decimal characters from the method's argument.
      Since:
      17.1
    • prettyPrint

      String prettyPrint(Reader reader, String systemID) throws PrettyPrintException
      Pretty prints the given XML document. The oXygen pretty printing options are used.
      Parameters:
      reader - The reader with over the document that is to be pretty printed.
      systemID - The URL location where the current XML fragment to format and indent is located. This parameter is not required but it may be used to solves relative entities from the DOCTYPE declaration in the XML content.
      Returns:
      The pretty printed version of the XML document.
      Throws:
      PrettyPrintException - If the pretty printing failed.
      Since:
      17.1
    • newNonValidatingXMLReader

      XMLReader newNonValidatingXMLReader()
      Creates an XMLReader without validation.
      Returns:
      A new XML Reader.
    • newNonValidatingXMLReader

      XMLReaderWithGrammar newNonValidatingXMLReader(Object grammarCacheToken)
      Creates an XMLReader without validation and with the possibility to reuse the grammar pool. If you are parsing XML fragments with DOCTYPE many times in your operation this method will be faster than the newNonValidatingXMLReader() method.
      Usage example:
       String xml = new String("<!DOCTYPE map PUBLIC \"-//OASIS//DTD DITA Map//EN\" \"map.dtd\">\n" +
           "<map/>");
       Object grammarToken = null;
       for (int i = 0; i < 100000; i++) {
         XMLReaderWithGrammar readerAndCache = authorAccess.getXMLUtilAccess().newNonValidatingXMLReader(grammarToken);
         XMLReader reader = readerAndCache.getXmlReader();
         grammarToken = readerAndCache.getGrammarCache();
         reader.parse(new InputSource(new StringReader(xml)));
       }
       
      Parameters:
      grammarCacheToken - The grammar cache token, if not null, it will be used to cache the grammar pool.
      Returns:
      A new XML Reader with a grammar cache token which can be then reused on the same method to provide grammar caching.
    • getEntityResolver

      EntityResolver getEntityResolver()
      Get the same entity resolver Oxygen sets to its constructed SAX Parsers (which looks into the Oxygen options and document types for catalogs). The resolver also looks at the additionally set priority entity resolvers.
      Returns:
      the same entity resolver Oxygen sets to its constructed SAX Parsers (which looks into the Oxygen options and document types for catalogs).
      Since:
      12.1
    • getURIResolver

      URIResolver getURIResolver()
      Get the same URI resolver Oxygen sets to its constructed XSLT transformers (which looks into the Oxygen options and document types for catalogs). The resolver also looks at the additionally set priority URI resolvers.
      Returns:
      the same URI resolver Oxygen sets to its constructed XSLT transformers (which looks into the Oxygen options and document types for catalogs).
      Since:
      12.1
    • addPriorityEntityResolver

      void addPriorityEntityResolver(EntityResolver entityResolver)
      Add a priority entity resolver. For performance reasons, when Oxygen only needs the URL of an entity, it does not call the EntityResolver#resolveEntity(String, String) method because it also fetches the content of the entity. To intercept also these cases, your EntityResolver should extend the EntityUrlResolver interface.
      Parameters:
      entityResolver - The entity resolver which will be called with priority before Oxygen calls the standard resolvers which are based on the catalog files specified in the preferences catalogs list and in each document type association.
      Since:
      13
    • removePriorityEntityResolver

      void removePriorityEntityResolver(EntityResolver entityResolver)
      Remove a priority entity resolver.
      Parameters:
      entityResolver - The entity resolver which will be called with priority before Oxygen calls the standard resolvers which are based on the catalog files specified in the preferences catalogs list and in each document type association.
      Since:
      13
    • addPriorityURIResolver

      void addPriorityURIResolver(URIResolver uriResolver)
      Add a priority URI resolver.
      Parameters:
      uriResolver - The URI resolver which will be called with priority before Oxygen calls the standard resolvers which are based on the catalog files specified in the preferences catalogs list and in each document type association.
      Since:
      13
    • removePriorityURIResolver

      void removePriorityURIResolver(URIResolver uriResolver)
      Remove a priority URI resolver.
      Parameters:
      uriResolver - The URI resolver which will be called with priority before Oxygen calls the standard resolvers which are based on the catalog files specified in the preferences catalogs list and in each document type association.
      Since:
      13
    • threeWayAutoMerge

      @Deprecated MergeResult threeWayAutoMerge(String ancestor, String left, String right, MergeConflictResolutionMethods conflictResolutionMethod)
      Deprecated.
      since 19.1, please use the equivalent CompareUtilAccess utilities.
      Merges two strings representing XML files using a three way merging algorithm which needs an ancestor file.
      Parameters:
      ancestor - The original file string which has been modified into left and right.
      left - The left version of the file string, the one with "our" changes.
      right - The right version of the file string, the one with "others" changes.
      conflictResolutionMethod - The conflict resolution method to use.
      Returns:
      A merged file string where conflicts are resolved by using the left version of the file or null if the merge encountered an error.
      Since:
      17.1
    • getXMLStructureAsDTD

      String getXMLStructureAsDTD(Reader reader)
      Get the structure of the provided XML document as a DTD.
      Parameters:
      reader - The reader representing the XML document to get the learn structure for.
      Returns:
      The learn structure as a DTD schema.
      Since:
      27

      *********************************
      EXPERIMENTAL - Subject to change
      ********************************

      Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.