Module (Gravia :: Runtime :: API 1.1.0.Beta13 API)

All Known Implementing Classes:

AbstractModule
```
public interface Module
```
An installed module in the Runtime.
A module must have a unique ResourceIdentity in the Runtime.
Gravia stays out of the business of resolving module's at runtime. Every module has an associated ClassLoader when it is installed in the runtime already. Modularity must be dealt with in the layer using the Gravia runtime.
For example, a servlet container like Tomcat may choose to create one Module per web application. Multiple modules may share the same class loader or may even all have the same class loader association. This allows GRavia to run on a flat class path (e.g. a plain JUnit test)
When installed it is also assigned a long identity, chosen by the Runtime. This identity does not change during the lifecycle of a module. Uninstalling and then reinstalling the module creates a new unique long identity.
A module can be in one of six states:
- Module.State.INSTALLED
- State#RESOLVED
- Module.State.STARTING
- Module.State.ACTIVE
- Module.State.STOPPING
- Module.State.UNINSTALLED
A module should only have active threads of execution when its state is one of STARTING,ACTIVE, or STOPPING. An UNINSTALLED module can not be set to another state; it can only be reached because references are kept somewhere.
The Runtime is the only entity that is allowed to create Module objects, and these objects are only valid within the Runtime that created them.
Modules have a natural ordering such that if two Modules have the same module id they are equal. A Module is less than another Module if it has a lower module id and is greater if it has a higher module id.
Since:

27-Sep-2013

Author:

thomas.diesler@jboss.com

Thread Safety: Thread Safe

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class Module.State
A module can be in one of five states:

Nested Classes
Modifier and Type	Interface and Description
`static class`	`Module.State` A module can be in one of five states:

Method Summary

Methods
Modifier and Type	Method and Description
`<A> A`	`adapt(Class<A> type)` Addapt this module to another type.
`List<URL>`	`findEntries(String path, String filePattern, boolean recurse)` Returns entries in this module.
`File`	`getDataFile(String filename)` Creates a `File` object for a file in the persistent storage area provided for this module by the Runtime.
`URL`	`getEntry(String path)` Returns a URL to the entry at the specified path in this module.
`List<String>`	`getEntryPaths(String path)` Returns an Enumeration of all the paths (`String` objects) to entries within this module whose longest sub-path matches the specified path.
`Dictionary<String,String>`	`getHeaders()` Returns this module's headers and values that where given on module installation.
`org.jboss.gravia.resource.ResourceIdentity`	`getIdentity()` Get the identity of this module.
`ModuleContext`	`getModuleContext()` Returns this module's `ModuleContext`.
`long`	`getModuleId()` Returns this module's unique identifier.
`Module.State`	`getState()` Returns this module's current state.
`Class<?>`	`loadClass(String className)` Loads the specified class using this module's class loader.
`void`	`start()` Starts this module.
`void`	`stop()` Stops this module.
`void`	`uninstall()` Uninstalls this module.

- Method Detail
  - adapt
```
<A> A adapt(Class<A> type)
```
    Addapt this module to another type.
    All modules support
    - Runtime
    - ClassLoader
    - Resource
    - ModuleContext
    Returns:
    Null if the module cannot be adapted to the requested type
  - getIdentity
```
org.jboss.gravia.resource.ResourceIdentity getIdentity()
```
    Get the identity of this module.
  - getModuleId
```
long getModuleId()
```
    Returns this module's unique identifier. Each module is assigned a unique identifier by the Runtime when it was installed.
    A module's unique identifier has the following attributes:
    - Is unique and persistent.
    - Is a long.
    - Its value is not reused for another module, even after a module is uninstalled.
    - Does not change while a module remains installed.
    This method must continue to return this module's unique identifier while this module is in the UNINSTALLED state.
    Returns:
    The unique runtime id of this module.
  - getState
```
Module.State getState()
```
    Returns this module's current state.
    
    See Also:
    Module.State
  - getModuleContext
```
ModuleContext getModuleContext()
```
    Returns this module's ModuleContext. The returned ModuleContext can be used by the caller to act on behalf of this module.
    If this module is not in the Module.State.STARTING, Module.State.ACTIVE, or Module.State.STOPPING states, then this module has no valid ModuleContext.
    
    Returns:
    A ModuleContext for this module or null if this module has no valid ModuleContext.
  - getHeaders
```
Dictionary<String,String> getHeaders()
```
    Returns this module's headers and values that where given on module installation.
    These values may be mapped to manifest headers, but this is not a requirement. The module's header values do not change durint the lifecycle of the module.
    Header names are case-insensitive. The methods of the returned Dictionary object must operate on header names in a case-insensitive manner.
    This method must continue to return header information while this module is in the UNINSTALLED state.
    
    Returns:
    An unmodifiable Dictionary object containing this module's Manifest headers and values.
  - getEntry
```
URL getEntry(String path)
```
    Returns a URL to the entry at the specified path in this module. This modules's class loader is not used to search for the entry. Only the contents of this module are searched for the entry.
    The specified path is always relative to the root of this module and may begin with "/". A path value of "/" indicates the root of this module.
    
    Parameters:
    path - The path name of the entry.
    
    Returns:
    A URL to the entry, or null if no entry could be found.
  - getEntryPaths
```
List<String> getEntryPaths(String path)
```
    Returns an Enumeration of all the paths (String objects) to entries within this module whose longest sub-path matches the specified path. This module's class loader is not used to search for entries. Only the contents of this module are searched.
    The specified path is always relative to the root of this module and may begin with a "/". A path value of "/" indicates the root of this module.
    Returned paths indicating subdirectory paths end with a "/". The returned paths are all relative to the root of this module and must not begin with "/".
    
    Parameters:
    path - The path name for which to return entry paths.
    
    Returns:
    A list of the entry paths (String objects).
  - findEntries
```
List<URL> findEntries(String path,
                    String filePattern,
                    boolean recurse)
```
    Returns entries in this module. This module's class loader is not used to search for entries. Only the contents of this module is searched for the specified entries.
    URLs for directory entries must have their path end with "/".
    
    Parameters:
    path - The path name in which to look. The path is always relative to the root of this module and may begin with "/". A path value of "/" indicates the root of this module.
    filePattern - The file name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the entry path. If the entry is a directory then the trailing "/" is not used for pattern matching. Substring matching is supported, as specified in the Filter specification, using the wildcard character ("*"). If null is specified, this is equivalent to "*" and matches all files.
    recurse - If true, recurse into subdirectories. Otherwise only return entries from the specified path.
    
    Returns:
    A list of URL objects for each matching entry.
  - start
```
void start()
           throws ModuleException
```
    Starts this module.
    If this module's state is UNINSTALLED then an IllegalStateException is thrown.
    The following steps are required to start this module:
    1. If this module is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a ModuleException is thrown to indicate this module was unable to be started.
    2. If this module's state is ACTIVE then this method returns immediately.
    3. This module's state is set to STARTING.
    4. A module event of type ModuleEvent.STARTING is fired.
    5. The ModuleActivator.start(ModuleContext) method if one is specified, is called. If the ModuleActivator is invalid or throws an exception then:
      
      This module's state is set to STOPPING.
      A module event of type ModuleEvent.STOPPING is fired.
      Any services registered by this module must be unregistered.
      Any services used by this module must be released.
      Any listeners registered by this module must be removed.
      This module's state is set to RESOLVED.
      A module event of type ModuleEvent.STOPPED is fired.
      A ModuleException is then thrown.
    6. This module's state is set to ACTIVE.
    7. A module event of type ModuleEvent.STARTED is fired.
    Throws:
    
    ModuleException - If the module cannot be started
  - stop
```
void stop()
          throws ModuleException
```
    Stops this module.
    If this module's state is UNINSTALLED then an IllegalStateException is thrown.
    The following steps are required to stop this module:
    1. If this module is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a ModuleException is thrown to indicate this module was unable to be stopped.
    2. If this module's state is not ACTIVE then this method returns immediately.
    3. This module's state is set to STOPPING.
    4. A module event of type ModuleEvent.STOPPING is fired.
    5. The ModuleActivator.stop(ModuleContext) method of this module's ModuleActivator, if one is specified, is called. If that method throws an exception, this method must continue to stop this module and a ModuleException must be thrown after completion of the remaining steps.
    6. Any services registered by this module must be unregistered.
    7. Any services used by this module must be released.
    8. Any listeners registered by this module must be removed.
    9. This module's state is set to RESOLVED.
    10. A module event of type ModuleEvent.STOPPED is fired.
    Throws:
    
    ModuleException - If the module cannot be started
  - uninstall
```
void uninstall()
```
    Uninstalls this module.
    This method causes the Runtime to notify other modules that this module is being uninstalled, and then puts this module into the UNINSTALLED state. The Runtime must remove any resources related to this module that it is able to remove.
    If this module's state is UNINSTALLED then an IllegalStateException is thrown.
    The following steps are required to uninstall a module:
    1. This module is stopped as described in the Module.stop method.
    2. This module's state is set to UNINSTALLED.
    3. A module event of type ModuleEvent.UNINSTALLED is fired.
  - loadClass
```
Class<?> loadClass(String className)
                   throws ClassNotFoundException
```
    Loads the specified class using this module's class loader.
    If this module's state is UNINSTALLED, then an IllegalStateException is thrown.
    
    Parameters:
    className - The name of the class to load.
    
    Returns:
    The Class object for the requested class.
    
    Throws:
    
    ClassNotFoundException
  - getDataFile
```
File getDataFile(String filename)
```
    Creates a File object for a file in the persistent storage area provided for this module by the Runtime. This method will return null if the platform does not have file system support.
    A File object for the base directory of the persistent storage area provided for this module by the Runtime can be obtained by calling this method with an empty string as filename.
    If the Java Runtime Environment supports permissions, the Runtime will ensure that this module has the java.io.FilePermission with actions read,write,delete for all files (recursively) in the persistent storage area provided for this module.
    
    Parameters:
    filename - A relative name to the file to be accessed.
    
    Returns:
    A File object that represents the requested file or null if the platform does not have file system support.
    
    Throws:
    
    IllegalStateException - If this module has been uninstalled.

Interface Module

Nested Class Summary

Method Summary

Method Detail

adapt

getIdentity

getModuleId

getState

getModuleContext

getHeaders

getEntry

getEntryPaths

findEntries

start

stop

uninstall

loadClass

getDataFile