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:
1.0
Author:
Reuters PLC

Method Summary
 BaseNode findReference(java.lang.String reference, boolean useExternal)
          Look up a reference to a NewsML node.
 java.lang.String getBaseURL()
          Get the base URL for the document.
 NewsMLFactory getFactory()
          Get the factory for creating new NewsML documents.
 BaseNode getRootNode()
          Get the root node of the current NewsML document.
 java.net.URL resolveHref(java.lang.String href)
          Resolve a reference.
 

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(java.lang.String reference,
                              boolean useExternal)
                       throws java.io.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.

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:
The NewsML node, if one could be located, or null otherwise.

getBaseURL

public java.lang.String getBaseURL()
Get the base URL for the document.
Returns:
The base URL.
See Also:
resolveHref(String)

resolveHref

public java.net.URL resolveHref(java.lang.String href)
                         throws java.net.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:
java.net.MalformedURLException - if the href cannot be resolved into a URL (this can be caught as an IOException).
See Also:
getBaseURL()