Package org.jboss.modules

# Class Module

java.lang.Object
org.jboss.modules.Module

public final class Module extends Object
A module is a unit of classes and other resources, along with the specification of what is imported and exported by this module from and to other modules. Modules are created by `ModuleLoader`s which build modules from various configuration information and resource roots.

Author:
  David M. Lloyd, John Bailey, Flavia Rainone, Jason T. Greene, thomas.diesler@jboss.com

## Method Summary

Modifier and Type
Method
Description
`static <T> Iterable<T>`
`findServices(Class<T> type, Predicate<Class<?>> filter, ClassLoader loader)`
Returns an iterable of available and filtered providers of given type.
`static Module`
`forClass(Class<?> clazz)`
Get the module for a loaded class, or `null` if the class did not come from any module.
`static Module`
`forClassLoader(ClassLoader cl, boolean search)`
Get the module for a class loader, or `null` if the class loader is not associated with any module.
`static ModuleLoader`
`getBootModuleLoader()`
Gets the boot module loader.
`static Module`
`getCallerModule()`
Get the caller's module.
`static ModuleLoader`
`getCallerModuleLoader()`
Gets the current module loader.
`ModuleClassLoader`
`getClassLoader()`
Get the class loader for a module.
`static ModuleLoader`
`getContextModuleLoader()`
Get the current thread's context module loader.
`DependencySpec[]`
`getDependencies()`
Get the current dependencies of this module.
`Set<String>`
`getExportedPaths()`
Get all the paths exported by this module.
`URL`
`getExportedResource(String name)`
Get an exported resource URL.
`Resource`
`getExportedResource(String rootPath, String resourcePath)`
Deprecated.
Resource root names are deprecated.
`Enumeration<URL>`
`getExportedResources(String name)`
Get all exported resource URLs for a resource name.
`ModuleIdentifier`
`getIdentifier()`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `getName()` instead.
`Set<String>`
`getImportedPaths()`
Get the (unmodifiable) set of paths which are imported into this module class loader, including local paths.
`Module`
`getModule(String name)`
Get the module with the given identifier from the module loader used by this module.
`Module`
`getModule(ModuleIdentifier identifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `getModule(String)` instead.
`static Module`
`getModuleFromCallerModuleLoader(String name)`
Get a module from the current module loader.
`static Module`
`getModuleFromCallerModuleLoader(ModuleIdentifier identifier)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `getModuleFromCallerModuleLoader(String)` instead.
`ModuleLoader`
`getModuleLoader()`
Get the module loader which created this module.
`static ModuleLogger`
`getModuleLogger()`
Get the logger used by the module system.
`String`
`getName()`
Get this module's name.
`PermissionCollection`
`getPermissionCollection()`
Get the module's configured permission collection.
`static String`
`getPlatformIdentifier()`
Get the platform identifier.
`static org.jboss.modules._private.ModulesPrivateAccess`
`getPrivateAccess()`
Private access for module internal code.
`String`
`getProperty(String name)`
Get the property with the given name, or `null` if none was defined.
`String`
`getProperty(String name, String defaultVal)`
Get the property with the given name, or a default value if none was defined.
`List<String>`
`getPropertyNames()`
Get a copy of the list of property names.
`static long`
`getStartTime()`
Return the start time in millis when Module.class was loaded.
`static ModuleLoader`
`getSystemModuleLoader()`
Get the system module loader.
`Version`
`getVersion()`
Get the module version.
`Iterator<Resource>`
`globResources(String glob)`
Enumerate all imported resources in this module which match the given glob expression.
`Iterator<Resource>`
`iterateResources(PathFilter filter)`
Enumerate all the imported resources in this module, subject to a path filter.
`static Class<?>`
`loadClassFromBootModuleLoader(String name, String className)`
Load a class from a module in the system module loader.
`static Class<?>`
`loadClassFromBootModuleLoader(ModuleIdentifier moduleIdentifier, String className)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadClassFromBootModuleLoader(String, String)` instead.
`static Class<?>`
`loadClassFromCallerModuleLoader(String name, String className)`
Load a class from a module in the caller's module loader.
`static Class<?>`
`loadClassFromCallerModuleLoader(ModuleIdentifier moduleIdentifier, String className)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadClassFromCallerModuleLoader(String, String)` instead.
`<S> ServiceLoader<S>`
`loadService(Class<S> serviceType)`
Load a service loader from this module.
`<S> ServiceLoader<S>`
`loadServiceDirectly(Class<S> serviceType)`
Load a service loader from this module, without looking at dependencies.
`static <S> ServiceLoader<S>`
`loadServiceFromCallerModuleLoader(String name, Class<S> serviceType)`
Load a service loader from a module in the caller's module loader.
`static <S> ServiceLoader<S>`
`loadServiceFromCallerModuleLoader(ModuleIdentifier identifier, Class<S> serviceType)`
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadServiceFromCallerModuleLoader(String, Class)` instead.
`static void`
`registerContentHandlerFactoryModule(Module module)`
Register an additional module which contains content handlers.
`static void`
`registerURLStreamHandlerFactoryModule(Module module)`
Register an additional module which contains URL handlers.
`void`
`run(String[] args)`
Run a module's main class, if any.
`void`
`run(String className, String[] args)`
Run the given main class in this module.
`static void`
`setModuleLogger(ModuleLogger logger)`
Change the logger used by the module system.
`String`
`toString()`
Get the string representation of this module.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Method Details

### getPrivateAccess

public static org.jboss.modules._private.ModulesPrivateAccess getPrivateAccess()
Private access for module internal code. Throws `SecurityException` for user code.

Throws:
  `SecurityException` - always

### getDependencies

public DependencySpec[] getDependencies() throws SecurityException
Get the current dependencies of this module.

Returns:
  the current dependencies of this module
Throws:
  `SecurityException` - if a security manager is enabled and the caller does not have the `getDependencies` `RuntimePermission`

### getExportedResource

@Deprecated public Resource getExportedResource(String rootPath, String resourcePath)
Deprecated.
Resource root names are deprecated.
Get an exported resource from a specific root in this module.

Parameters:
  `rootPath` - the module root to search
  `resourcePath` - the path of the resource
Returns:
  the resource

### run

public void run(String[] args) throws NoSuchMethodException, InvocationTargetException, ClassNotFoundException
Run a module's main class, if any.

Parameters:
  `args` - the arguments to pass
Throws:
  `NoSuchMethodException` - if there is no main method
  `InvocationTargetException` - if the main method failed
  `ClassNotFoundException` - if the main class is not found

### run

public void run(String className, String[] args) throws NoSuchMethodException, InvocationTargetException, ClassNotFoundException
Run the given main class in this module.

Parameters:
  `className` - the class name to run (must not be `null`)
  `args` - the arguments to pass
Throws:
  `NoSuchMethodException` - if there is no main method
  `InvocationTargetException` - if the main method failed
  `ClassNotFoundException` - if the main class is not found

### getIdentifier

@Deprecated(forRemoval=true) public ModuleIdentifier getIdentifier()
Deprecated, for removal: This API element is subject to removal in a future version.
Use `getName()` instead.
Get this module's identifier.

Returns:
  the identifier

### getName

public String getName()
Get this module's name.

Returns:
  this module's name

### getModuleLoader

public ModuleLoader getModuleLoader()
Get the module loader which created this module.

Returns:
  the module loader of this module

### loadService

public <S> ServiceLoader<S> loadService(Class<S> serviceType)
Load a service loader from this module.

Type Parameters:
  `S` - the service type
Parameters:
  `serviceType` - the service type class
Returns:
  the service loader

### loadServiceDirectly

public <S> ServiceLoader<S> loadServiceDirectly(Class<S> serviceType)
Load a service loader from this module, without looking at dependencies.

Type Parameters:
  `S` - the service type
Parameters:
  `serviceType` - the service type class
Returns:
  the service loader

### loadServiceFromCallerModuleLoader

@Deprecated(forRemoval=true) public static <S> ServiceLoader<S> loadServiceFromCallerModuleLoader(ModuleIdentifier identifier, Class<S> serviceType) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadServiceFromCallerModuleLoader(String, Class)` instead.
Load a service loader from a module in the caller's module loader. The caller's module loader refers to the loader of the module of the class that calls this method. Note that `loadService(Class)` is more efficient since it does not need to crawl the stack.

Type Parameters:
  `S` - the service type
Parameters:
  `identifier` - the module identifier containing the service loader
  `serviceType` - the service type class
Returns:
  the loaded service from the caller's module
Throws:
  `ModuleLoadException` - if the named module failed to load

### loadServiceFromCallerModuleLoader

public static <S> ServiceLoader<S> loadServiceFromCallerModuleLoader(String name, Class<S> serviceType) throws ModuleLoadException
Load a service loader from a module in the caller's module loader. The caller's module loader refers to the loader of the module of the class that calls this method. Note that `loadService(Class)` is more efficient since it does not need to crawl the stack.

Type Parameters:
  `S` - the service type
Parameters:
  `name` - the module name containing the service loader
  `serviceType` - the service type class
Returns:
  the loaded service from the caller's module
Throws:
  `ModuleLoadException` - if the named module failed to load

### getClassLoader

public ModuleClassLoader getClassLoader()
Get the class loader for a module. The class loader can be used to access non-exported classes and resources of the module.

If a security manager is present, then this method invokes the security manager's `checkPermission` method with a `RuntimePermission("getClassLoader")` permission to verify access to the class loader. If access is not granted, a `SecurityException` will be thrown.

Returns:
  the module class loader

### getExportedPaths

public Set<String> getExportedPaths()
Get all the paths exported by this module.

Returns:
  the paths that are exported by this module

### forClass

public static Module forClass(Class<?> clazz)
Get the module for a loaded class, or `null` if the class did not come from any module.

Parameters:
  `clazz` - the class
Returns:
  the module it came from

### forClassLoader

public static Module forClassLoader(ClassLoader cl, boolean search)
Get the module for a class loader, or `null` if the class loader is not associated with any module. If the class loader is unknown, it is possible to check the parent class loader up the chain, and so on until a module is found.

Parameters:
  `cl` - the class loader
  `search` - `true` to search up the delegation chain
Returns:
  the associated module

### getBootModuleLoader

public static ModuleLoader getBootModuleLoader()
Gets the boot module loader. The boot module loader is the initial loader that is established by the module framework. It typically is based off of the environmental module path unless it is overridden by specifying a different class name for the `boot.module.loader` system property.

Returns:
  the boot module loader

### getSystemModuleLoader

public static ModuleLoader getSystemModuleLoader()
Get the system module loader. This is the module loader which contains the Java platform modules, plus a module for JBoss Modules itself, called `org.jboss.modules`.

Returns:
  the system module loader

### findServices

public static <T> Iterable<T> findServices(Class<T> type, Predicate<Class<?>> filter, ClassLoader loader)
Returns an iterable of available and filtered providers of given type.

Parameters:
  `type` - service provider type
  `filter` - to specify which providers to load
  `loader` - to be used for providers lookup
Returns:
  An iterable of available and filtered providers of given type

### getCallerModuleLoader

public static ModuleLoader getCallerModuleLoader()
Gets the current module loader. The current module loader is the loader of the module from the calling class. Note that this method must crawl the stack to determine this, so other mechanisms are more efficient.

Returns:
  the current module loader, or `null` if this method is called outside of a module

### getContextModuleLoader

public static ModuleLoader getContextModuleLoader()
Get the current thread's context module loader. This loader is the one which defined the module whose class loader is, or is a parent of, the thread's current context class loader. If there is none, then `null` is returned.

Returns:
  the module loader, or `null` if none is set

### getModuleFromCallerModuleLoader

@Deprecated(forRemoval=true) public static Module getModuleFromCallerModuleLoader(ModuleIdentifier identifier) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `getModuleFromCallerModuleLoader(String)` instead.
Get a module from the current module loader. Note that this must crawl the stack to determine this, so other mechanisms are more efficient.

Parameters:
  `identifier` - the module identifier
Returns:
  the module
Throws:
  `ModuleLoadException` - if the module could not be loaded
See Also:
  - `getCallerModuleLoader()`

### getModuleFromCallerModuleLoader

public static Module getModuleFromCallerModuleLoader(String name) throws ModuleLoadException
Get a module from the current module loader. Note that this must crawl the stack to determine this, so other mechanisms are more efficient.

Parameters:
  `name` - the module name
Returns:
  the module
Throws:
  `ModuleLoadException` - if the module could not be loaded
See Also:
  - `getCallerModuleLoader()`

### getCallerModule

public static Module getCallerModule()
Get the caller's module. The caller's module is the module containing the method that calls this method. Note that this method crawls the stack so other ways of obtaining the module are more efficient.

Returns:
  the current module

### getModule

@Deprecated(forRemoval=true) public Module getModule(ModuleIdentifier identifier) throws ModuleLoadException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `getModule(String)` instead.
Get the module with the given identifier from the module loader used by this module.

Parameters:
  `identifier` - the module identifier
Returns:
  the module
Throws:
  `ModuleLoadException` - if an error occurs

### getModule

public Module getModule(String name) throws ModuleLoadException
Get the module with the given identifier from the module loader used by this module.

Parameters:
  `name` - the module name
Returns:
  the module
Throws:
  `ModuleLoadException` - if an error occurs

### loadClassFromBootModuleLoader

@Deprecated(forRemoval=true) public static Class<?> loadClassFromBootModuleLoader(ModuleIdentifier moduleIdentifier, String className) throws ModuleLoadException, ClassNotFoundException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadClassFromBootModuleLoader(String, String)` instead.
Load a class from a module in the system module loader.

Parameters:
  `moduleIdentifier` - the identifier of the module from which the class should be loaded
  `className` - the class name to load
Returns:
  the class
Throws:
  `ModuleLoadException` - if the module could not be loaded
  `ClassNotFoundException` - if the class could not be loaded
See Also:
  - `getBootModuleLoader()`

### loadClassFromBootModuleLoader

public static Class<?> loadClassFromBootModuleLoader(String name, String className) throws ModuleLoadException, ClassNotFoundException
Load a class from a module in the system module loader.

Parameters:
  `name` - the name of the module from which the class should be loaded
  `className` - the class name to load
Returns:
  the class
Throws:
  `ModuleLoadException` - if the module could not be loaded
  `ClassNotFoundException` - if the class could not be loaded
See Also:
  - `getBootModuleLoader()`

### loadClassFromCallerModuleLoader

@Deprecated(forRemoval=true) public static Class<?> loadClassFromCallerModuleLoader(ModuleIdentifier moduleIdentifier, String className) throws ModuleLoadException, ClassNotFoundException
Deprecated, for removal: This API element is subject to removal in a future version.
Use `loadClassFromCallerModuleLoader(String, String)` instead.
Load a class from a module in the caller's module loader.

Parameters:
  `moduleIdentifier` - the identifier of the module from which the class should be loaded
  `className` - the class name to load
Returns:
  the class
Throws:
  `ModuleLoadException` - if the module could not be loaded
  `ClassNotFoundException` - if the class could not be loaded
See Also:
  - `getCallerModuleLoader()`

### loadClassFromCallerModuleLoader

public static Class<?> loadClassFromCallerModuleLoader(String name, String className) throws ModuleLoadException, ClassNotFoundException
Load a class from a module in the caller's module loader.

Parameters:
  `name` - the name of the module from which the class should be loaded
  `className` - the class name to load
Returns:
  the class
Throws:
  `ModuleLoadException` - if the module could not be loaded
  `ClassNotFoundException` - if the class could not be loaded
See Also:
  - `getCallerModuleLoader()`

### getExportedResource

public URL getExportedResource(String name)
Get an exported resource URL.

Parameters:
  `name` - the resource name
Returns:
  the resource, or `null` if it was not found

### getExportedResources

public Enumeration<URL> getExportedResources(String name)
Get all exported resource URLs for a resource name.

Parameters:
  `name` - the resource name
Returns:
  the resource URLs

### iterateResources

public Iterator<Resource> iterateResources(PathFilter filter) throws ModuleLoadException
Enumerate all the imported resources in this module, subject to a path filter. The filter applies to the containing path of each resource.

Parameters:
  `filter` - the filter to apply to the search
Returns:
  the resource iterator (possibly empty)
Throws:
  `ModuleLoadException` - if linking a dependency module fails for some reason

### globResources

public Iterator<Resource> globResources(String glob) throws ModuleLoadException
Enumerate all imported resources in this module which match the given glob expression. The glob applies to the whole resource name.

Parameters:
  `glob` - the glob to apply
Returns:
  the iterator
Throws:
  `ModuleLoadException` - if linking a dependency module fails for some reason

### getImportedPaths

public Set<String> getImportedPaths() throws ModuleLoadException
Get the (unmodifiable) set of paths which are imported into this module class loader, including local paths. The set will include all paths defined by the module's resource loaders, minus any paths excluded by filters. The set will generally always contain an empty entry (""). The set is unordered and unsorted, and is iterable in O(n) time and accessible in O(1) time.

Returns:
  the set of paths
Throws:
  `ModuleLoadException` - if the module was previously unlinked, and there was an exception while linking

### getProperty

public String getProperty(String name)
Get the property with the given name, or `null` if none was defined.

Parameters:
  `name` - the property name
Returns:
  the property value

### getProperty

public String getProperty(String name, String defaultVal)
Get the property with the given name, or a default value if none was defined.

Parameters:
  `name` - the property name
  `defaultVal` - the default value
Returns:
  the property value

### getPropertyNames

public List<String> getPropertyNames()
Get a copy of the list of property names.

Returns:
  the property names list

### getVersion

public Version getVersion()
Get the module version.

Returns:
  the module version, or `null` if none was set

### toString

public String toString()
Get the string representation of this module.

Overrides:
  `toString` in class `Object`
Returns:
  the string representation

### getModuleLogger

public static ModuleLogger getModuleLogger()
Get the logger used by the module system.

If a security manager is present, then this method invokes the security manager's `checkPermission` method with a `RuntimePermission("accessModuleLogger")` permission to verify access to the module logger. If access is not granted, a `SecurityException` will be thrown.

Returns:
  the module logger

### setModuleLogger

public static void setModuleLogger(ModuleLogger logger)
Change the logger used by the module system.

If a security manager is present, then this method invokes the security manager's `checkPermission` method with a `RuntimePermission("accessModuleLogger")` permission to verify access to the module logger. If access is not granted, a `SecurityException` will be thrown.

Parameters:
  `logger` - the new logger, must not be `null`

### getStartTime

public static long getStartTime()
Return the start time in millis when Module.class was loaded.

Returns:
  start time of Module.class load

### registerContentHandlerFactoryModule

public static void registerContentHandlerFactoryModule(Module module)
Register an additional module which contains content handlers.

If a security manager is present, then this method invokes the security manager's `checkPermission` method with a `RuntimePermission("addContentHandlerFactory")` permission to verify access. If access is not granted, a `SecurityException` will be thrown.

Parameters:
  `module` - the module to add

### registerURLStreamHandlerFactoryModule

public static void registerURLStreamHandlerFactoryModule(Module module)
Register an additional module which contains URL handlers.

If a security manager is present, then this method invokes the security manager's `checkPermission` method with a `RuntimePermission("addURLStreamHandlerFactory")` permission to verify access. If access is not granted, a `SecurityException` will be thrown.

Parameters:
  `module` - the module to add

### getPlatformIdentifier

public static String getPlatformIdentifier()
Get the platform identifier. This is the string that uniquely identifies the hardware and OS combination for the current running system.

Returns:
  the platform identifier

### getPermissionCollection

public PermissionCollection getPermissionCollection()
Get the module's configured permission collection.

Returns:
  the module permission collection