org.freecompany.brimstone.module
Class Module

java.lang.Object
  extended by org.freecompany.brimstone.module.Module

public class Module
extends java.lang.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  java.net.URL base
           
protected static java.util.Map<java.lang.String,Module> cache
           
static java.lang.String CONTENT_TYPE
           
protected  org.freecompany.util.xml.editor.XmlEditor editor
           
static java.lang.String[] EXTRACT_NAME
           
static java.lang.String NAMESPACE
           
protected static org.freecompany.util.multicaster.Notification notifier
           
protected  java.util.List<Module> resolved
           
 
Constructor Summary
Module(java.net.URL url)
          Creates a new module from the given URL without resolving modules.
Module(java.net.URL url, boolean resolve)
          Creates a new module from the given URL, optionally resolving component modules.
Module(java.net.URLConnection connection)
          Creates a {$link Module} by loading the XML content referenced by the provided connection.
Module(java.net.URLConnection connection, boolean resolve)
          Creates a {$link Module} by loading the XML content referenced by the provided connection and optionally resolves all references.
 
Method Summary
static java.lang.String alias(java.lang.String uri)
          Determines the proper alias name for a given fully qualified versioned artifact.
 java.net.URL getBase()
          Retrieves the {$link URL} of this module descriptor.
 java.net.URL getComponent(java.lang.String alias)
          Loads a component URL by alias.
 java.util.Collection<java.net.URL> getComponents()
          Returns an Iterable collection of URL instances that refer to each of the components of this module.
 java.util.Collection<java.net.URL> getDependencies()
          Returns an Iterable collection of URL instances that refer to each of the dependencies of this module.
 java.lang.String getExtension(java.lang.String namespace, java.lang.String prefix, java.lang.String path)
          Returns a node containing the content of the extensions section of the descriptor for this module.
 org.w3c.dom.Element getExtensions()
          Returns a node containing the content of the extensions section of the descriptor for this module.
 java.lang.String getJavadoc()
          Retrieves a {$link String} containing the path to the Javadoc documentation for the code this module packages.
 java.lang.String getName()
          Retrieves the name of this module.
protected  java.util.Collection<java.net.URL> getUrls(java.lang.String path)
           
 java.lang.String getVersion()
          Retrieves the version of this module.
static java.lang.Object load(java.net.URL url)
          Loads a module URL and any fragment part it may contain.
 void resolve()
          Resolves component and dependent modules to enable fallthrough on alias lookups.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

NAMESPACE

public static final java.lang.String NAMESPACE
See Also:
Constant Field Values

CONTENT_TYPE

public static final java.lang.String CONTENT_TYPE
See Also:
Constant Field Values

EXTRACT_NAME

public static final java.lang.String[] EXTRACT_NAME

notifier

protected static final org.freecompany.util.multicaster.Notification notifier

cache

protected static java.util.Map<java.lang.String,Module> cache

editor

protected final org.freecompany.util.xml.editor.XmlEditor editor

resolved

protected java.util.List<Module> resolved

base

protected java.net.URL base
Constructor Detail

Module

public Module(java.net.URLConnection connection)
       throws java.io.IOException,
              org.xml.sax.SAXException
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:
java.io.IOException - if the content cannot be loaded.
org.xml.sax.SAXException - if the content is not a valid XML document.

Module

public Module(java.net.URLConnection connection,
              boolean resolve)
       throws java.io.IOException,
              org.xml.sax.SAXException
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:
java.io.IOException - if the content cannot be loaded.
org.xml.sax.SAXException - if the content is not a valid XML document.

Module

public Module(java.net.URL url)
       throws java.io.IOException,
              org.xml.sax.SAXException
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:
java.io.IOException - if the content cannot be loaded.
org.xml.sax.SAXException - if the content is not a valid XML document.

Module

public Module(java.net.URL url,
              boolean resolve)
       throws java.io.IOException,
              org.xml.sax.SAXException
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 getComponent( String alias) 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.
Throws:
java.io.IOException
org.xml.sax.SAXException
Method Detail

getBase

public java.net.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.

getName

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

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

getVersion

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

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

getJavadoc

public java.lang.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.

getExtension

public java.lang.String getExtension(java.lang.String namespace,
                                     java.lang.String prefix,
                                     java.lang.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 org.w3c.dom.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.

getComponent

public java.net.URL getComponent(java.lang.String alias)
                          throws java.net.MalformedURLException
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.
Throws:
java.net.MalformedURLException

getComponents

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

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

getDependencies

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

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

resolve

public void resolve()
             throws java.net.MalformedURLException,
                    java.io.IOException
Resolves component and dependent modules to enable fallthrough on alias lookups. This works by locally caching and loading each component module definition.

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

getUrls

protected java.util.Collection<java.net.URL> getUrls(java.lang.String path)
                                              throws java.net.MalformedURLException
Throws:
java.net.MalformedURLException

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

alias

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

Returns:
a normalized alias for the given artifact.

load

public static java.lang.Object load(java.net.URL url)
                             throws java.net.MalformedURLException,
                                    java.io.IOException
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.
Throws:
java.net.MalformedURLException
java.io.IOException