|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.openide.xml.XMLUtil
public final class XMLUtil
Utility class collecting library methods related to XML processing.
Remember that when parsing XML files you often want to set an explicit entity resolver. For example, consider a file such as this:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE root PUBLIC "-//NetBeans//DTD Foo 1.0//EN" "http://www.netbeans.org/dtds/foo-1_0.dtd"> <root/>
If you parse this with a null entity resolver, or you use the
default resolver (EntityCatalog.getDefault()
) but do not do
anything special with this DTD, you will probably find the parse
blocking to make a network connection even when you are not
validating. That is because DTDs can be used to define
entities and other XML oddities, and are not a pure constraint
language like Schema or RELAX-NG.
There are three basic ways to avoid the network connection.
Register the DTD. This is generally the best thing to do. See
EntityCatalog
's documentation for details, but for example
in your layer use:
<filesystem> <folder name="xml"> <folder name="entities"> <folder name="NetBeans"> <file name="DTD_Foo_1_0" url="nbres:/org/netbeans/modules/mymod/resources/foo-1_0.dtd"> <attr name="hint.originalPublicID" stringvalue="-//NetBeans//DTD Foo 1.0//EN"/> </file> </folder> </folder> </folder> </filesystem>
Now the default system entity catalog will resolve the public ID to the local copy in your module, not the network copy. Additionally, anyone who mounts the "NetBeans Catalog" in the XML Entity Catalogs node in the Runtime tab will be able to use your local copy of the DTD automatically, for validation, code completion, etc. (The network URL should really exist, though, for the benefit of other tools!)
You can also set an explicit entity resolver which maps that particular public ID to some local copy of the DTD, if you do not want to register it globally in the system for some reason. If handed other public IDs, just return null to indicate that the system ID should be loaded.
In some cases where XML parsing is very performance-sensitive, and you know that you do not need validation and furthermore that the DTD defines no infoset (there are no entity or character definitions, etc.), you can speed up the parse. Turn off validation, but also supply a custom entity resolver that does not even bother to load the DTD at all:
public InputSource resolveEntity(String pubid, String sysid) throws SAXException, IOException { if (pubid.equals("-//NetBeans//DTD Foo 1.0//EN")) { return new InputSource(new ByteArrayInputStream(new byte[0])); } else { return EntityCatalog.getDefault().resolveEntity(pubid, sysid); } }
Method Summary | |
---|---|
static org.w3c.dom.Document |
createDocument(java.lang.String rootQName,
java.lang.String namespaceURI,
java.lang.String doctypePublicID,
java.lang.String doctypeSystemID)
Creates empty DOM Document using JAXP factoring. |
static org.xml.sax.XMLReader |
createXMLReader()
Create a simple parser. |
static org.xml.sax.XMLReader |
createXMLReader(boolean validate)
Create a simple parser, possibly validating. |
static org.xml.sax.XMLReader |
createXMLReader(boolean validate,
boolean namespaceAware)
Create a SAX parser from the JAXP factory. |
static byte[] |
fromHex(char[] hex,
int start,
int len)
Decodes data encoded using toHex . |
static org.w3c.dom.Document |
parse(org.xml.sax.InputSource input,
boolean validate,
boolean namespaceAware,
org.xml.sax.ErrorHandler errorHandler,
org.xml.sax.EntityResolver entityResolver)
Create from factory a DocumentBuilder and let it create a org.w3c.dom.Document. |
static java.lang.String |
toAttributeValue(java.lang.String val)
Escape passed string as XML attibute value ( < , & , ' and "
will be escaped. |
static java.lang.String |
toElementContent(java.lang.String val)
Escape passed string as XML element content ( < ,
& and > |
static java.lang.String |
toHex(byte[] val,
int start,
int len)
Can be used to encode values that contain invalid XML characters. |
static void |
validate(org.w3c.dom.Element data,
javax.xml.validation.Schema schema)
Check whether a DOM tree is valid according to a schema. |
static void |
write(org.w3c.dom.Document doc,
java.io.OutputStream out,
java.lang.String enc)
Writes a DOM document to a stream. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static org.xml.sax.XMLReader createXMLReader() throws org.xml.sax.SAXException
createXMLReader(false, false)
org.xml.sax.SAXException
public static org.xml.sax.XMLReader createXMLReader(boolean validate) throws org.xml.sax.SAXException
validate
- if true, a validating parser is returned
createXMLReader(validate, false)
org.xml.sax.SAXException
public static org.xml.sax.XMLReader createXMLReader(boolean validate, boolean namespaceAware) throws org.xml.sax.SAXException
See class Javadoc for hints on setting an entity resolver. This parser has its entity resolver set to the system entity resolver chain.
validate
- if true, a validating parser is returnednamespaceAware
- if true, a namespace aware parser is returned
javax.xml.parsers.FactoryConfigurationError
- Application developers should never need to directly catch errors of this type.
org.xml.sax.SAXException
- if a parser fulfilling given parameters can not be createdpublic static org.w3c.dom.Document createDocument(java.lang.String rootQName, java.lang.String namespaceURI, java.lang.String doctypePublicID, java.lang.String doctypeSystemID) throws org.w3c.dom.DOMException
Document doc = createDocument("book", null, null, null);
creates new DOM of a well-formed document with root element named book.
rootQName
- qualified name of root element. e.g. myroot
or ns:myroot
namespaceURI
- URI of root element namespace or null
doctypePublicID
- public ID of DOCTYPE or null
doctypeSystemID
- system ID of DOCTYPE or null
if no DOCTYPE
required and doctypePublicID is also null
org.w3c.dom.DOMException
- if new DOM with passed parameters can not be created
javax.xml.parsers.FactoryConfigurationError
- Application developers should never need to directly catch errors of this type.public static org.w3c.dom.Document parse(org.xml.sax.InputSource input, boolean validate, boolean namespaceAware, org.xml.sax.ErrorHandler errorHandler, org.xml.sax.EntityResolver entityResolver) throws java.io.IOException, org.xml.sax.SAXException
input
- a parser input (for URL users use: new InputSource(url.toExternalForm())
validate
- if true validating parser is usednamespaceAware
- if true DOM is created by namespace aware parsererrorHandler
- a error handler to notify about exception or null
entityResolver
- SAX entity resolver or null
; see class Javadoc for hints
java.io.IOException
- if an I/O problem during parsing occurs
org.xml.sax.SAXException
- is thrown if a parser error occurs
javax.xml.parsers.FactoryConfigurationError
- Application developers should never need to directly catch errors of this type.public static void write(org.w3c.dom.Document doc, java.io.OutputStream out, java.lang.String enc) throws java.io.IOException
Important: There might be some problems with
<![CDATA[ ]]>
sections in the DOM tree you pass into this method. Specifically,
some CDATA sections my not be written as CDATA section or may be merged with
other CDATA section at the same level. Also if plain text nodes are mixed with
CDATA sections at the same level all text is likely to end up in one big CDATA section.
For nodes that only have one CDATA section this method should work fine.
doc
- DOM document to be writtenout
- data sinkenc
- XML-defined encoding name (e.g. "UTF-8")
java.io.IOException
- if JAXP fails or the stream cannot be written topublic static void validate(org.w3c.dom.Element data, javax.xml.validation.Schema schema) throws org.xml.sax.SAXException
Element fragment = ...; SchemaFactory f = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI); Schema s = f.newSchema(This.class.getResource("something.xsd")); try { XMLUtil.validate(fragment, s); // valid } catch (SAXException x) { // invalid }
data
- a DOM treeschema
- a parsed schema
org.xml.sax.SAXException
- if validation failedpublic static java.lang.String toAttributeValue(java.lang.String val) throws java.io.CharConversionException
<
, &
, '
and "
will be escaped.
Note: An XML processor returns normalized value that can be different.
val
- a string to be escaped
java.io.CharConversionException
- if val contains an improper XML characterpublic static java.lang.String toElementContent(java.lang.String val) throws java.io.CharConversionException
<
,
&
and > in ]]>
sequences).
- Parameters:
val
- a string to be escaped
- Returns:
- escaped value
- Throws:
java.io.CharConversionException
- if val contains an improper XML character- Since:
- 1.40
public static java.lang.String toHex(byte[] val, int start, int len)
val
- data to be convertedstart
- offsetlen
- countpublic static byte[] fromHex(char[] hex, int start, int len) throws java.io.IOException
toHex
.
hex
- data to be convertedstart
- offsetlen
- count
java.io.IOException
- if input does not represent hex encoded value
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |