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.
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 String | alias(String uri)
Determines the proper alias name for a given fully qualified versioned artifact.
|
URL | getBase()
Retrieves the {$link URL} of this module descriptor. |
URL | getComponent(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.
|
String | getExtension(String namespace, String prefix, String path)
Returns a node containing the content of the extensions section of the
descriptor for this module. |
Element | getExtensions()
Returns a node containing the content of the extensions section of the
descriptor for this module. |
String | getJavadoc()
Retrieves a {$link String} containing the path to the Javadoc
documentation for the code this module packages. |
String | getName()
Retrieves the name of this module.
|
protected Collection<URL> | getUrls(String path) |
String | getVersion()
Retrieves the version of this module.
|
static Object | load(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. |
protected URL base
protected static Map<String,
Module> cache
public static final String CONTENT_TYPE
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.
public static final String[] EXTRACT_NAME
protected static final Notification notifier
public static final String NAMESPACE
protected List<
Module> resolved
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
public String getName()
Retrieves the name of this module.
Returns: the name of this module as specified in the descriptor.
protected Collection<URL> getUrls(String path)
public String getVersion()
Retrieves the version of this module.
Returns: the version of this module as specified in the descriptor.
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.
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.