org.freecompany.brimstone.module

Class Module

public class Module extends Object

A module is a collection of components and dependencies as well as relevant meta data. A module is serialized as an XML document instance of the schema http://www.freecompany.org/namespace/brimstone/module which contains this information.

A component consists of a URI describing a resource, either as a URL or a Brimstone specific URI that can be resolved to a particular resource, and an optional component name. The component name can be used to reference a discrete component and defaults to the file name as interpreted from the URI or URL specification. Components are exposed by name in order to decouple the particular implementation version from it's final use. A component URI may reference another module definition. In this case, the module behaves as if the component module's component and dependency (as well as other) entries existed within the local module. Therefore accessing the component or dependency lists will return a superset of the components of both this module and it's component modules. Furthermore, alias lookups will resolve within both the current module and any component modules.

A dependency consists of a URI matching the convention of a component declaration and has no associated name.

All operations within this class assume that the provided descriptor has been validated against the schema. If this is not the case and the document is not valid, the behavior is undefined. In particular ClassCastExceptions might be thrown from various methods that attempt to manipulate the document.

Field Summary
protected URLbase
protected static Map<String,Module>cache
static StringCONTENT_TYPE
protected XmlEditoreditor
Initializes the JVM static factories for connection handling.
static String[]EXTRACT_NAME
protected static Notificationnotifier
static StringNAMESPACE
protected List<Module>resolved
Constructor Summary
Module(URLConnection connection)
Creates a {$link Module} by loading the XML content referenced by the provided connection.
Module(URLConnection connection, boolean resolve)
Creates a {$link Module} by loading the XML content referenced by the provided connection and optionally resolves all references.
Module(URL url)
Creates a new module from the given URL without resolving modules.
Module(URL url, boolean resolve)
Creates a new module from the given URL, optionally resolving component modules.
Method Summary
static Stringalias(String uri)
Determines the proper alias name for a given fully qualified versioned artifact.
URLgetBase()
Retrieves the {$link URL} of this module descriptor.
URLgetComponent(String alias)
Loads a component URL by alias.
Collection<URL>getComponents()
Returns an Iterable collection of URL instances that refer to each of the components of this module.
Collection<URL>getDependencies()
Returns an Iterable collection of URL instances that refer to each of the dependencies of this module.
StringgetExtension(String namespace, String prefix, String path)
Returns a node containing the content of the extensions section of the descriptor for this module.
ElementgetExtensions()
Returns a node containing the content of the extensions section of the descriptor for this module.
StringgetJavadoc()
Retrieves a {$link String} containing the path to the Javadoc documentation for the code this module packages.
StringgetName()
Retrieves the name of this module.
protected Collection<URL>getUrls(String path)
StringgetVersion()
Retrieves the version of this module.
static Objectload(URL url)
Loads a module URL and any fragment part it may contain.
voidresolve()
Resolves component and dependent modules to enable fallthrough on alias lookups.

Field Detail

base

protected URL base

cache

protected static Map<String,Module> cache

CONTENT_TYPE

public static final String CONTENT_TYPE

editor

protected final XmlEditor editor
Initializes the JVM static factories for connection handling. This static block eliminates multiple initializations on this class object, but if this class is loaded in parallel in another class loader multiple invocations could be possible. So, we catch the Error that is generated in that case.

Note: this means that it is also possible that if this class is loaded after the application has set a content handler that does not support the Module type or a stream handler that does not recognize the "brimstone" URN namespace it will fail silently and cause strange behavior, in particular excetions relating to unsupported protocols and URL#getContent calls which do not successfully return Module instances when they should.

EXTRACT_NAME

public static final String[] EXTRACT_NAME

notifier

protected static final Notification notifier

NAMESPACE

public static final String NAMESPACE

resolved

protected List<Module> resolved

Constructor Detail

Module

public Module(URLConnection connection)
Creates a {$link Module} by loading the XML content referenced by the provided connection. This constructor behaves the same as calling {$link #Module( URLConnection, boolean)} with the second parameter false.

Parameters: connection the connection from which to load the descriptor.

Throws: IOException if the content cannot be loaded. SAXException if the content is not a valid XML document.

Module

public Module(URLConnection connection, boolean resolve)
Creates a {$link Module} by loading the XML content referenced by the provided connection and optionally resolves all references.

Parameters: connection the connection from which to load the descriptor. resolve flag indicating whether references should be initially resolved.

Throws: IOException if the content cannot be loaded. SAXException if the content is not a valid XML document.

Module

public Module(URL url)
Creates a new module from the given URL without resolving modules. This constructor behaves the same as calling {$link #Module( URL, boolean)} with the second parameter false.

Parameters: url URL the url of the module definition to load.

Throws: IOException if the content cannot be loaded. SAXException if the content is not a valid XML document.

Module

public Module(URL url, boolean resolve)
Creates a new module from the given URL, optionally resolving component modules. If the resolve flag is true, any component URI that points to a module definition will be preloaded and indexed for use in resolving aliases. When resolved in this fashion, calls to Module will automatically fallthrough to included component modules as well.

Note that this constructor does not simply pass the resolve flag to the next constructor. This is because the base URL must be set before attempting to resolve the module.

Parameters: url URL of the module definition to load. resolve flag indicating whether to resolve component modules.

Method Detail

alias

public static String alias(String uri)
Determines the proper alias name for a given fully qualified versioned artifact.

Returns: a normalized alias for the given artifact.

getBase

public URL getBase()
Retrieves the {$link URL} of this module descriptor. This {$link URL} can be used for building more complex {$link URL} strings that can resolve aliases within the this descriptor through anchors.

Returns: the {$link URL} of this module descriptor.

getComponent

public URL getComponent(String alias)
Loads a component URL by alias. If this module has been resolved via the resolve method, this call will fall through to component modules in the event that this module has no associated alias.

Parameters: alias component alias to dereference.

Returns: a component URL corresponding to the alias.

getComponents

public Collection<URL> getComponents()
Returns an Iterable collection of URL instances that refer to each of the components of this module.

Throws: MalformedURLException if any of the module components is an invalid reference.

getDependencies

public Collection<URL> getDependencies()
Returns an Iterable collection of URL instances that refer to each of the dependencies of this module.

Throws: MalformedURLException if any of the module dependencies is an invalid reference.

getExtension

public String getExtension(String namespace, String prefix, String path)
Returns a node containing the content of the extensions section of the descriptor for this module. Concrete extension classes should filter the resulting node by namespace to retrieve relevant extension code.

TODO: The content should be accessible by namespace and non-prefixed path only.

Parameters: namespace the namespace of the extension. prefix the prefix within the document of this extension. path the prefixed path to the setting relative to the extensions element.

Returns: a String representing the extension setting at the given path.

getExtensions

public Element getExtensions()
Returns a node containing the content of the extensions section of the descriptor for this module. Concrete extension classes should filter the resulting node by namespace to retrieve relevant extension code.

Returns: a Element containing the extensions element.

getJavadoc

public String getJavadoc()
Retrieves a {$link String} containing the path to the Javadoc documentation for the code this module packages. This setting is optional.

Returns: the path to this module's documentation or the empty {$link String} if none exists.

getName

public String getName()
Retrieves the name of this module.

Returns: the name of this module as specified in the descriptor.

getUrls

protected Collection<URL> getUrls(String path)

getVersion

public String getVersion()
Retrieves the version of this module.

Returns: the version of this module as specified in the descriptor.

load

public static Object load(URL url)
Loads a module URL and any fragment part it may contain. If this URL references a module definition it will be loaded and, if it has no fragment, returned as is. If a fragment is present it will be resolved to a URI and returned. If the provided URL does not reference a module definition, null is returned.

Parameters: url URL describing the module definition to load.

Returns: an instance of Module if the URL references a module, a URL if it has a fragment that points to a particular component of the module, or null if it does not reference a module.

resolve

public void resolve()
Resolves component and dependent modules to enable fallthrough on alias lookups. This works by locally caching and loading each component module definition.

Throws: MalformedURLException if any of the module components or dependencies is an invalid reference. IOException if an error occurs while caching the artifact.