Qwylt

java.lang.module.spi
Class ImportSpace

java.lang.Object
  extended by java.lang.module.ResourceSpace
      extended by java.lang.module.ClassSpace
          extended by java.lang.module.spi.ImportSpace
All Implemented Interfaces:
java.lang.Iterable<PackageConnection>

public class ImportSpace
extends ClassSpace
implements java.lang.Iterable<PackageConnection>

A ClassSpace that provides a view onto a set of imported ClassSpaces, one per package, that meet a specified set of constraints. During construction, each instance acts as the domain to which the constraints are applied.

During the import preparation phase, an instance of this class is constructed and populated with candidate archives, one or more per package. The state of each candidate is checked, and connection initiated if required; this recursive process ensures that all candidates reach the prepared or failed state before the commit phase begins.

All PREPARE constraints are applied during this phase, potentially removing candidate archives from the domain; a ConnectionError is thrown if the set of candidates for an imported package becomes empty.

During the import commit phase, all COMMIT constraints are applied, again potentially removing candidate archives from the domain and failing if the set of candidates becomes empty.

Once committed, instances of this class are ready to act as a ClassSpace for the importing module. For each imported package, there exists a connection with at least one candidate archive that is itself in the connected state. Each connection lazily instantiates a Module from a selected candidate and returns it as the ClassSpace for that package.

Since:
Dec 30, 2008
Author:
Bryan Atsatt

Field Summary
static java.util.Enumeration<java.net.URL> EMPTY_ENUMERATION
          An empty Enumeration instance.
 
Constructor Summary
protected ImportSpace(int initialCapacity, ModuleArchive importer, ImportConstraint... constraints)
          Constructs a new instance with the specified initial capacity and constraints.
  ImportSpace(ModuleArchive importer)
          Constructs a new instance with default constraints.
  ImportSpace(ModuleArchive importer, ImportConstraint... constraints)
          Constructs a new instance with the specified constraints.
 
Method Summary
 void addConnection(java.lang.String packageName, Import theImport, java.util.List<? extends ModuleArchive> candidates)
          Add candidate connections for the specified package name.
 void addConnections(ImportSpace imports)
          Add all connections from the specified imports.
 void addConnectionsForModuleImport(Import theImport, ModuleArchive candidate)
          Add the specified candidate for each package it directly exports.
 void addConnectionsForService(java.util.List<? extends ModuleArchive> archives)
          Add required service provider connections.
protected  void assertNoConflict(ModuleArchive candidate, PackageConnection connection)
          Assert that the specified candidate does not conflict with the existing candidates.
protected  void commit()
          Commit this PackageSpace by asserting all constraints that apply in the commit phase.
static ImportSpace emptyImports(ModuleArchive importer)
          Returns an empty, immutable and committed ImportSpace for the specified importer.
 PackageConnection getConnection(java.lang.String packageName)
          Returns the connection for the specified package name.
 PackageConnection[] getConnections()
          Returns the connections.
 java.util.Set<java.lang.String> getExportedPackages()
          Returns an unmodifiable set of package names exported by this ClassSpace.
 java.util.Set<ModuleArchive> getImported()
          Returns the target archive from each connection.
 java.util.Set<java.lang.String> getImportedPackages()
          Returns an unmodifiable set of the package names imported by this ClassSpace.
 ModuleArchive getImporter()
          Returns the archive for which this instance was created.
 java.lang.String getName()
          Returns the name of this ClassSpace.
 ClassSpace getPackageProvider(java.lang.String packageName)
          Returns the ClassSpace that provides the specified package.
 java.util.Set<java.lang.String> getReExports()
          Returns the set of package names that are re-exported by this ClassSpace.
 java.net.URL getResource(java.lang.String resourcePath)
          Returns the first resource with the specified path name.
 java.nio.ByteBuffer getResourceData(java.lang.String resourcePath)
          Returns the data for the specified resource or null if not found.
 java.util.Enumeration<java.net.URL> getResources(java.lang.String resourcePath)
          Returns all resources with the specified path name.
 java.util.List<ModuleArchive> getServiceProviders(java.lang.String serviceName)
          Returns the ModuleArchives that provide the specified service.
 Version getVersion()
          Returns the version of this ClassSpace.
 boolean isCommitted()
          Returns true if this connection has been committed.
 boolean isStored()
          Returns whether or not this instance has been stored.
 java.util.Iterator<PackageConnection> iterator()
          Returns an iterator over the connections contained in this ClassSpace, in no particular order.
 boolean load(Streams.In in)
          Load this instance from the specified stream.
 java.lang.Class<?> loadClass(java.lang.String className)
          Loads the class with the specified binary name.
 java.lang.Class<?> loadLocalClass(java.lang.String className, java.lang.String packageName)
          Loads the exported class with the specified name without delegating to other providers.
protected  PackageConnection newConnection(PackageConnection.ConnectionType type, java.lang.String packageName, java.util.List<? extends ModuleArchive> candidates)
          Create a connection for the specified package.
protected  PackageConnection newConnection(PackageConnection.ConnectionType type, java.lang.String packageName, ModuleArchive candidate)
          Create a connection for the specified package.
protected  void prepare()
          Prepare this PackageSpace by asserting all constraints that apply in the prepare phase.
 PackageConnection removeConnection(java.lang.String packageName)
          Removes the connection for the specified package name.
protected  void setConnection(PackageConnection connection)
          Set a connection.
 int size()
          Returns the number of connections in this ClassSpace.
 void store(Streams.Out out)
          Store this instance into the specified stream.
static ImportSpace union(ImportSpace[] imports)
          Returns a committed ClassSpace that is the union of the specified list of committed ImportSpace instances.
static ImportSpace union(ImportSpace source, java.lang.String packageName, Import packageImport, java.util.List<ModuleArchive> candidates, ImportConstraint... constraints)
          Returns a a committed ClassSpace that is the union of the specified committed source space and one additional package connection.
 
Methods inherited from class java.lang.module.ClassSpace
getPackageName
 
Methods inherited from class java.lang.module.ResourceSpace
equals, getResourcePackageName, hashCode, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

EMPTY_ENUMERATION

public static final java.util.Enumeration<java.net.URL> EMPTY_ENUMERATION
An empty Enumeration instance.

Constructor Detail

ImportSpace

public ImportSpace(ModuleArchive importer)
Constructs a new instance with default constraints.

Parameters:
importer - The importing archive.

ImportSpace

public ImportSpace(ModuleArchive importer,
                   ImportConstraint... constraints)
Constructs a new instance with the specified constraints.

Parameters:
importer - The importing archive.
constraints - The constraints.

ImportSpace

protected ImportSpace(int initialCapacity,
                      ModuleArchive importer,
                      ImportConstraint... constraints)
Constructs a new instance with the specified initial capacity and constraints.

Parameters:
initialCapacity - The initial capacity.
importer - The importing archive.
constraints - The constraints.
Method Detail

emptyImports

public static ImportSpace emptyImports(ModuleArchive importer)
Returns an empty, immutable and committed ImportSpace for the specified importer.

Parameters:
importer - The importer.
Returns:
The ImportSpace.

union

public static ImportSpace union(ImportSpace[] imports)
Returns a committed ClassSpace that is the union of the specified list of committed ImportSpace instances.

Parameters:
imports - The list of committed instances.
Returns:
The committed ClassSpace.
Throws:
java.lang.IllegalStateException - if the list is null, or empty, or if any of the instances is not committed.
ConnectionError - If any of the imports conflict. A conflict occurs when more than one instance contains a connection for a given package and the connections refer to different instances.

union

public static ImportSpace union(ImportSpace source,
                                java.lang.String packageName,
                                Import packageImport,
                                java.util.List<ModuleArchive> candidates,
                                ImportConstraint... constraints)
Returns a a committed ClassSpace that is the union of the specified committed source space and one additional package connection.

Parameters:
source - The committed source instance.
packageName - The package name for the additional connection.
packageImport - The package import for the additional connection.
candidates - The candidates for the additional connection.
constraints - The constraints to apply to the union.
Returns:
The committed instance.
Throws:
ConnectionError - if the union cannot be committed.

isCommitted

public boolean isCommitted()
Returns true if this connection has been committed.

Returns:
true if this connection is shared; false otherwise.

isStored

public boolean isStored()
Returns whether or not this instance has been stored.

Returns:
true if storee, false if not.

getImporter

public ModuleArchive getImporter()
Returns the archive for which this instance was created.

Returns:
The importing archive.

getConnection

public PackageConnection getConnection(java.lang.String packageName)
Returns the connection for the specified package name.

Parameters:
packageName - The '.' separated package name.
Returns:
The PackageConnection or null if not found.

addConnectionsForModuleImport

public void addConnectionsForModuleImport(Import theImport,
                                          ModuleArchive candidate)
Add the specified candidate for each package it directly exports.

Parameters:
candidate - The candidate connection.
theImport - The import.
Throws:
ConnectionError - If candidates for the exported packages are already present and the new candidate is not a member of that set.
java.lang.IllegalArgumentException - If the candidate is the importer.

addConnection

public void addConnection(java.lang.String packageName,
                          Import theImport,
                          java.util.List<? extends ModuleArchive> candidates)
Add candidate connections for the specified package name.

Parameters:
packageName - The package name.
theImport - The import.
candidates - The candidate connections.
Throws:
ConnectionError - If candidates for the specified package are already present and any of the new candidates is not a member of that set.
java.lang.IllegalArgumentException - If any of the candidates is the importer or if the candidates do not export the specified package.

addConnections

public void addConnections(ImportSpace imports)
Add all connections from the specified imports.

Parameters:
imports - The imports.
Throws:
ConnectionError - If imports contains a conflicting import for any package.

assertNoConflict

protected void assertNoConflict(ModuleArchive candidate,
                                PackageConnection connection)
Assert that the specified candidate does not conflict with the existing candidates.

Parameters:
candidate - The candidate.
connection - The connection containing the existing candidates.
Throws:
ConnectionError - If the candidate is not already present in the existing candidates list.

newConnection

protected PackageConnection newConnection(PackageConnection.ConnectionType type,
                                          java.lang.String packageName,
                                          ModuleArchive candidate)
Create a connection for the specified package.

Parameters:
type - The connection type.
packageName - The package provided by the connection.
candidate - The candidate connection provider for the specified package.
Returns:
The connection.

newConnection

protected PackageConnection newConnection(PackageConnection.ConnectionType type,
                                          java.lang.String packageName,
                                          java.util.List<? extends ModuleArchive> candidates)
Create a connection for the specified package.

Parameters:
type - The connection type.
packageName - The package provided by the connection.
candidates - The candidate connection providers for the specified package.
Returns:
The connection.

setConnection

protected void setConnection(PackageConnection connection)
Set a connection.

Parameters:
connection - The connection.

removeConnection

public PackageConnection removeConnection(java.lang.String packageName)
Removes the connection for the specified package name.

Parameters:
packageName - The '.' separated package name.
Returns:
The removed PackageConnection or null if not found.

iterator

public java.util.Iterator<PackageConnection> iterator()
Returns an iterator over the connections contained in this ClassSpace, in no particular order.

Specified by:
iterator in interface java.lang.Iterable<PackageConnection>
Returns:
The connection iterator.

getConnections

public PackageConnection[] getConnections()
Returns the connections.

Returns:
The connections.

getImported

public java.util.Set<ModuleArchive> getImported()
Returns the target archive from each connection.

Returns:
The archives.
Throws:
ConnectionError - if not committed.

prepare

protected void prepare()
Prepare this PackageSpace by asserting all constraints that apply in the prepare phase.

Throws:
ConnectionError - if connections cannot be prepared.

commit

protected void commit()
Commit this PackageSpace by asserting all constraints that apply in the commit phase.

Throws:
ConnectionError - if connections cannot be committed.

size

public int size()
Returns the number of connections in this ClassSpace.

Returns:
The size.

getName

public java.lang.String getName()
Returns the name of this ClassSpace.

Specified by:
getName in class ResourceSpace
Returns:
The name.

getVersion

public Version getVersion()
Returns the version of this ClassSpace.

Specified by:
getVersion in class ResourceSpace
Returns:
The version.

getImportedPackages

public java.util.Set<java.lang.String> getImportedPackages()
Returns an unmodifiable set of the package names imported by this ClassSpace.

Specified by:
getImportedPackages in class ResourceSpace
Returns:
the set of imported package names.

getExportedPackages

public java.util.Set<java.lang.String> getExportedPackages()
Returns an unmodifiable set of package names exported by this ClassSpace.

Specified by:
getExportedPackages in class ResourceSpace
Returns:
The set of exported package names.

getPackageProvider

public ClassSpace getPackageProvider(java.lang.String packageName)
Returns the ClassSpace that provides the specified package.

Specified by:
getPackageProvider in class ClassSpace
Parameters:
packageName - The package name.
Returns:
The provider, which may be this instance, or null if package is not exported.

getServiceProviders

public java.util.List<ModuleArchive> getServiceProviders(java.lang.String serviceName)
Returns the ModuleArchives that provide the specified service.

Specified by:
getServiceProviders in class ClassSpace
Parameters:
serviceName - The service interface class name.
Returns:
The providers, empty if none.

addConnectionsForService

public void addConnectionsForService(java.util.List<? extends ModuleArchive> archives)
Add required service provider connections.

Parameters:
archives - The service providers.

loadClass

public java.lang.Class<?> loadClass(java.lang.String className)
                             throws java.lang.ClassNotFoundException
Loads the class with the specified binary name.

Specified by:
loadClass in class ClassSpace
Parameters:
className - The binary name of the class to be loaded.
Returns:
The resulting Class object.
Throws:
java.lang.ClassNotFoundException - If the class was not found.

loadLocalClass

public java.lang.Class<?> loadLocalClass(java.lang.String className,
                                         java.lang.String packageName)
                                  throws java.lang.ClassNotFoundException
Loads the exported class with the specified name without delegating to other providers.

Specified by:
loadLocalClass in class ClassSpace
Parameters:
className - The binary name of the class to be loaded.
packageName - The package name of the class to be loaded, "" if none.
Returns:
The resulting Class object.
Throws:
java.lang.ClassNotFoundException - If the class was not found.

getResourceData

public java.nio.ByteBuffer getResourceData(java.lang.String resourcePath)
Returns the data for the specified resource or null if not found.

Specified by:
getResourceData in class ResourceSpace
Parameters:
resourcePath - The relative path to the resource, which must use '/' as the path separator and must not have '/' as the first character.
Returns:
A read-only buffer or null if the resource is not contained in this instance.

getResource

public java.net.URL getResource(java.lang.String resourcePath)
Returns the first resource with the specified path name.

Specified by:
getResource in class ResourceSpace
Parameters:
resourcePath - The '/' separated relative resource path, which must not have a leading '/'.
Returns:
The resource or null if not found.

getResources

public java.util.Enumeration<java.net.URL> getResources(java.lang.String resourcePath)
                                                 throws java.io.IOException
Returns all resources with the specified path name.

Specified by:
getResources in class ResourceSpace
Parameters:
resourcePath - The '/' separated relative resource path, which must not have a leading '/'.
Returns:
The resources, empty if not found.
Throws:
java.io.IOException - If an I/O error occurs.

getReExports

public java.util.Set<java.lang.String> getReExports()
Returns the set of package names that are re-exported by this ClassSpace.

Returns:
The set of re-exported package names.

store

public void store(Streams.Out out)
           throws java.io.IOException
Store this instance into the specified stream.

Parameters:
out - The stream.
Throws:
java.io.IOException - If a failure occurs.

load

public boolean load(Streams.In in)
             throws java.io.IOException
Load this instance from the specified stream.

Parameters:
in - The stream.
Returns:
true if result is valid, false if the data is out of sync.
Throws:
java.io.IOException - If a failure occurs.

Qwylt

Send comments or questions to Bryan Atsatt