com.xmlmind.xml.clipboard

Class ClipboardFormat

java.lang.Object

com.xmlmind.xml.clipboard.ClipboardFormat

public final class ClipboardFormat
extends Object

Utility class used to convert XML nodes to/from a string. This string uses a special serialized XML format called the clipboard format.

Field Summary

Fields

Modifier and Type	Field and Description
static Namespace	CLIPBOARD_NAMESPACE Namespace of the wrapper element used to to wrap multiple XML nodes when these nodes are copied to the clipboard.
static Name	ENVELOPE_NAME Name of the wrapper element used to wrap multiple XML nodes when these nodes are copied to the clipboard.
static Name[]	INCLUSION_PROPERTIES An array containing the names of all the properties added to a node having an inclusion property: Constants.INCLUSION_PROPERTY, Constants.SOURCE_URL_PROPERTY, Constants.READ_ONLY_PROPERTY.
static Name	TEXT_PLACEHOLDER_NAME Name of the element used to represent an empty text node.

Method Summary

Modifier and Type	Method and Description
static Node[]	checkForFormat(Node[] nodes, int nodeCount) Checks specified node array prior to using format(com.xmlmind.xml.doc.Node[], int, com.xmlmind.xml.name.PrefixEntry[], boolean).
static Node[]	docToNodes(Document doc) Convert specified document containing XML data in clipboard format to a sequence of Nodes.
static String	format(Node[] nodes, int nodeCount, PrefixEntry[] prefixes, boolean preserveInclusions) Converts specified nodes to a string which may be copied to the clipboard.
static Node[]	parse(File file) Equivalent to parse(FileUtil.fileToURL(file)).
static Node[]	parse(InputSource source) Parses the contents of specified source and returns parsed nodes.
static Node[]	parse(String string) Parses specified string and returns parsed nodes.
static Node[]	parse(URL url) Parses the contents of specified file and returns parsed nodes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLIPBOARD_NAMESPACE

public static final Namespace CLIPBOARD_NAMESPACE

Namespace of the wrapper element used to to wrap multiple XML nodes when these nodes are copied to the clipboard.

ENVELOPE_NAME

public static final Name ENVELOPE_NAME

Name of the wrapper element used to wrap multiple XML nodes when these nodes are copied to the clipboard.

TEXT_PLACEHOLDER_NAME

public static final Name TEXT_PLACEHOLDER_NAME

Name of the element used to represent an empty text node.

This element is useful when a included element is to be formatted. When such an element is then pasted in a document (after reparsing it using parse(String), we cannot normalize ignoreable whitespace as we do it for non-included elements (because an included element is marked read-only).

INCLUSION_PROPERTIES

public static final Name[] INCLUSION_PROPERTIES

An array containing the names of all the properties added to a node having an inclusion property: Constants.INCLUSION_PROPERTY, Constants.SOURCE_URL_PROPERTY, Constants.READ_ONLY_PROPERTY.

Method Detail

parse

public static Node[] parse(String string)

Parses specified string and returns parsed nodes.

Parameters:

string - the string to be parsed.

This string is expected to start with "<?xml ".

Moreover, this string is expected to contain XML data in clipboard format.

Returns:

parsed nodes or null if specified string cannot be parsed as XML.

parse

public static Node[] parse(File file)
                    throws IOException

Equivalent to parse(FileUtil.fileToURL(file)).

Throws:

IOException

parse

public static Node[] parse(URL url)
                    throws IOException

Parses the contents of specified file and returns parsed nodes.

Parameters:

url - URL of the file to be parsed.

This file is expected to contain XML data in clipboard format.

Returns:

parsed nodes or null if the contents of specified file cannot be parsed as XML.

Throws:

IOException - if an I/O error occurs during this operation

parse

public static Node[] parse(InputSource source)

Parses the contents of specified source and returns parsed nodes.

Parameters:

source - the XML source.

This source is expected to contain XML data in clipboard format.

Returns:

parsed nodes or null if the contents of specified source cannot be parsed as XML.

docToNodes

public static Node[] docToNodes(Document doc)

Convert specified document containing XML data in clipboard format to a sequence of Nodes.

• If the root element of specified document is an element having ENVELOPE_NAME as its name, this method returns the child nodes of the root element in an array.
• Otherwise, this method returns an array of nodes containing just the root element itself.

In both cases, nested ENVELOPE_NAME elements are automatically removed and replaced by their child nodes.

Note that each element contained in the returned array may be given a Constants.DECLARED_PREFIXES_PROPERTY property.

format

public static String format(Node[] nodes,
                            int nodeCount,
                            PrefixEntry[] prefixes,
                            boolean preserveInclusions)

Converts specified nodes to a string which may be copied to the clipboard.

Parameters:

nodes - the nodes to be formatted

nodeCount - the number of nodes available in nodes

prefixes - specifies which prefixes to use for the namespaces of elements contained in nodes. May be null, in which case automatically generated prefixes ns, ns2, ns3, etc, are used.

preserveInclusions - specifies whether inclusions should be preserved

Returns:

a plain text or an XML string representing specified nodes

See Also:

checkForFormat(com.xmlmind.xml.doc.Node[], int)

checkForFormat

public static Node[] checkForFormat(Node[] nodes,
                                    int nodeCount)

Checks specified node array prior to using format(com.xmlmind.xml.doc.Node[], int, com.xmlmind.xml.name.PrefixEntry[], boolean).

Parameters:

nodes - node array to be checked

nodeCount - number of nodes in nodes

Returns:

nodes if it can be formatted as is; otherwise a copy of nodes, containing for some nodes, a copy of this node with all properties related to inclusions recursively removed.

The latter case occurs when nodes does not specify a node range (for example, because specified nodes are not siblings or simply because they are not yet attached to the document tree) or when specified node range does not contain one or more inclusions as a whole.