org.newsml.toolkit
Interface NewsMLSession

public interface NewsMLSession

Meta-information for a NewsML session.

This interface provides a node-independent access point for getting and setting information about a NewsML session.

Version:

2.0

Author:

Reuters PLC

Method Summary

BaseNode	findReference(String reference, boolean useExternal) Look up a reference to a NewsML node.
String	getBaseURL() Get the base URL for the session.
NewsMLFactory	getFactory() Get the factory for creating new NewsML documents.
BaseNode	getNodeByDuid(String duid) Look up a node in the current document by Duid.
BaseNode	getNodeByXPath(BaseNode contextNode, String xpath) Get the first node matching an XPath expression.
BaseNode[]	getNodesByXPath(BaseNode contextNode, String xpath) Look up nodes in the current document by XPath.
BaseNode	getRootNode() Get the root node of the current NewsML document.
URL	resolveHref(String href) Resolve a reference.
void	setBaseURL(String baseURL) Set the base URL for the session.

Method Detail

getFactory

public NewsMLFactory getFactory()

Get the factory for creating new NewsML documents.

Returns:

The current NewsML factory (not null).

getRootNode

public BaseNode getRootNode()

Get the root node of the current NewsML document.

Returns:

An object representing the root node; the caller will have to cast it to the appropriate type.

findReference

public BaseNode findReference(String reference,
                              boolean useExternal)
                       throws IOException

Look up a reference to a NewsML node.

If the reference contains '#', the part following corresponds with a Duid in the target document (otherwise uses the root element); if the part preceding '#' is empty, the target document is the current document.

The getNodeByDuid(String) method is a little simpler and more efficient if you know for you're simply searching for a node that matches a specific Duid.

Parameters:

reference - The node reference, as a string in URI reference format (may include a '#').

useExternal - true to follow references in external URLs, false otherwise.

Returns:

A BaseNode (which must be cast to the appropriate type) or null if no match was found.

Throws:

IOException - if there is an error finding the node.

See Also:

getNodeByDuid(String)

getNodeByDuid

public BaseNode getNodeByDuid(String duid)

Look up a node in the current document by Duid.

This is a more restrictive (and slightly more efficient) version of findReference(java.lang.String, boolean); unlike findReference, this method does not require a leading '#' on the Duid (though it's optionally allowed), and does not throw an IOException.

[Please note that in the current DOM implementation, only a few node types are castable; everything else must remain as BaseNode].

Parameters:

duid - the document-unique identifier of the node to get.

Returns:

A BaseNode (which must be cast to the appropriate type) or null if no match was found.

See Also:

findReference(java.lang.String, boolean)

getNodesByXPath

public BaseNode[] getNodesByXPath(BaseNode contextNode,
                                  String xpath)
                           throws NewsMLException

Look up nodes in the current document by XPath.

This method looks up nodes by XPath, starting with the context node provided. Note that the XPath must match elements or no results will be returned (attribute matches are not currently supported, though attributes may be used in node tests).

Parameters:

contextNode - The starting point, or context node, for the XPath expression.

xpath - The XPath expression as a string.

Returns:

An possibly-empty array of matching nodes.

Throws:

NewsMLException - if the XPath expression provided is invalid.

getNodeByXPath

public BaseNode getNodeByXPath(BaseNode contextNode,
                               String xpath)
                        throws NewsMLException

Get the first node matching an XPath expression.

This method finds the first node matching the xpath expression provided, starting at the context node. Note that the XPath must match elements or no matching node will be found (attribute matches are not currently supported, though attributes may be used in node tests).

Parameters:

contextNode - The starting point, or context node, for the XPath expression.

xpath - The XPath expression as a string.

Returns:

The first node matching the expression, or null if there are no matches.

Throws:

NewsMLException - if the XPath expression provided is invalid.

getBaseURL

public String getBaseURL()

Get the base URL for the session.

Returns:

The base URL.

See Also:

setBaseURL(String), resolveHref(String)

setBaseURL

public void setBaseURL(String baseURL)

Set the base URL for the session.

Note that when a node is added as a child to another node, it adopts that node's session, and thus, may take on a different base URL.

Parameters:

baseURL - The base URL for resolving references.

See Also:

getBaseURL(), resolveHref(String)

resolveHref

public URL resolveHref(String href)
                throws MalformedURLException

Resolve a reference.

This method is useful for retrieving an external resource -- text or binary -- referenced from a NewsML package. See the standard Java URL class for information on how your application can use the URL returned to load remote resources. The method automatically resolves any relative hrefs against the NewsML document's base URL.

Parameters:

href - A (possibly relative) URL to resolve.

Returns:

The href resolved against the current document's base URL.

Throws:

MalformedURLException - if the href cannot be resolved into a URL (this can be caught as an IOException).

See Also:

getBaseURL()