[jboss-cvs] JBossAS SVN: r99620 - in projects/docs: classloading and 2 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Jan 19 18:13:09 EST 2010
Author: laubai
Date: 2010-01-19 18:13:09 -0500 (Tue, 19 Jan 2010)
New Revision: 99620
Added:
projects/docs/classloading/
projects/docs/classloading/docs/
projects/docs/classloading/docs/01.overview.txt
projects/docs/classloading/docs/02.abstractions.txt
projects/docs/classloading/docs/03.classloader.txt
projects/docs/classloading/docs/10.defineClass.txt
projects/docs/classloading/docs/11.policy.txt
projects/docs/classloading/docs/12.system.txt
projects/docs/classloading/docs/13.domain.txt
projects/docs/classloading/docs/14.parentPolicy.txt
projects/docs/classloading/docs/15.classFilter.txt
projects/docs/classloading/docs/16.JDKChecker.txt
projects/docs/classloading/docs/17.Loader.txt
projects/docs/classloading/docs/30.version.txt
projects/docs/classloading/docs/31.classloading.txt
projects/docs/classloading/docs/32.module.txt
projects/docs/classloading/docs/33.metadata.txt
projects/docs/classloading/docs/34.exportall.txt
projects/docs/classloading/docs/35.capabilities.txt
projects/docs/classloading/docs/36.requirements.txt
projects/docs/classloading/docs/37.resourceVisitor.txt
projects/docs/classloading/docs/40.xml.txt
projects/docs/classloading/docs/99.glossary.txt
projects/docs/classloading/examples/
projects/docs/classloading/examples/pom.xml
projects/docs/classloading/svn-commit.tmp
Log:
Added raw classloading documentation.
Added: projects/docs/classloading/docs/01.overview.txt
===================================================================
--- projects/docs/classloading/docs/01.overview.txt (rev 0)
+++ projects/docs/classloading/docs/01.overview.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,170 @@
+INTRODUCTION
+
+The following overview provides a fairly high level summary of the
+issues surrounding ClassLoading and some of the solutions that have
+been used to solve them.
+
+It's main purpose is to provide a brief rational for the overall goals of the
+JBoss ClassLoader framework. Don't worry if you don't understand
+all the issues straightaway. The rest of this document explains
+these issues more thoroughly than is possible in an overview.
+A glossary is provided for those that don't understand certain terms.
+
+CLASSLOADING
+
+ClassLoading is the JRE framework that allows user defined mechanisms to
+locate and load java classes. To take advantage of this feature a ClassLoader
+must be constructed by the user.
+
+ClassLoading is one of those features within java where it is easy
+to do simple things and notoriously difficult to do and understand harder
+things.
+
+Part of the reason why ClassLoading is difficult to understand
+is that it is dealing with many different issues:
+
+* Locating, defining and validating classes
+* Assigning security permissions to the loaded classes
+* Allowing multiple versions of a class to be loaded
+* Controlling the visibility of one class (version) from another
+* Serving as a contextual object on each thread (the "TCL")
+
+The purpose of this document is to describe how to use the JBoss ClassLoader
+framework which helps to make the use of ClassLoading simpler as well as
+providing additional features and abstractions to solve more complicated
+problems.
+
+JRE PROVIDED CLASSLOADERS
+
+For simple use cases, the JRE provides a notion of "classpath". This is really
+just a ClassLoader that loads classes and resources from archives and
+directories defined on the command line.
+
+The JRE also provides a URLClassLoader which effectively allows the
+user to create a "classpath" at runtime by providing a list of URLs.
+
+CLASSLOADER DELEGATION
+
+The JRE ClassLoaders only provide a parent-child delegation model
+where the parent is asked first to load a class then the classloader the user
+has constructed. For example, the "classpath" will ask the "System ClassLoader"
+to load classes before looking at those classes defined by the user.
+
+This works in simple cases but it makes it more difficult
+(if not impossible) to perform "hot deployment". Hot deployment is the
+mechanism where you can throw away a ClassLoader and then create
+a new one over some possibly changed classes. This allows classes
+to evolve without having to restart the runtime.
+
+With peer delegation models such as the UnifiedClassLoader (UCL)
+of JBossAS 3 and 4, the swapping of ClassLoader can be much more
+fine grained.
+
+CLASSLOADER DEPENDENCIES
+
+One of the issues with "hot deployment" however is that other
+ClassLoaders can become tightly coupled if their classes are using
+'call-by-reference".
+i.e. Classes from one ClassLoader can reference classes from another
+ClassLoader that you want to "hot deploy".
+
+The issue can be avoided by using "call-by-value" but it is less efficient.
+
+A different solution is ClassLoader dependencies. That is for one
+ClassLoader to reference classes from another ClassLoader it must specify
+a dependency on the ClassLoader from which it wants to load classes.
+By making that information available to the ClassLoading framework,
+it can automatically redeploy dependent ClassLoaders when the ClassLoaders
+they depend upon change.
+
+CLASS VISIBILTY
+
+Often a class that is public is not really meant for public consumption.
+An example might be an interface between two different components
+in the same framework.
+
+Similarly, an application may use another framework but not
+want to expose that to users of the application. e.g. it could use
+a logging framework internally.
+
+To support this idea, there should be a notion of "export" from a ClassLoader.
+That is only those packages that are stated as "exported"
+should be visible to classes from other ClassLoaders.
+
+CLASS ANNOTATION SCANNING
+
+Many of the JavaEE specs (and some other specs) are increasingly
+providing mechansims to define metadata using annotations on the
+classes rather than using xml files.
+
+The issue this has for ClassLoading is how to locate all the classes
+that are part of a ClassLoader given the many different mechansims.
+e.g. there is no generic way to list the contents of a URL.
+
+So as part of the pluggability mechanism for ClassLoader implementations,
+there should also be a way to plugin class discovery
+(assuming such a mechanism is possible for that implementation).
+
+CLASSLOADER ISOLATION AND MULTIPLE VERSIONS
+
+People want to have their own versions of classes
+without interferance from other ClassLoaders running in the same JRE.
+
+The two main reasons for this are usually because of incompatiblity
+problems.
+
+* A class doesn't understand contextual classloading or "leaks"
+information, usually through static variables
+
+* A class has changed in an incompatible way between versions
+which would break some applications if they all tried to use
+the same version.
+
+The typical solution is to use the "parent-child" delegation model
+but reverse it. That is load from the child first. This is called
+ClassLoader isolation or the "servlet spec model" since that spec
+recommends this type of ClassLoading.
+
+This can be inefficent since you have multiple copies of the classes
+consuming memory. It also leads to many problems when classes in the
+isolated ClassLoader want to call classes in different ClassLoaders
+that use different versions of the same classes.
+
+An alternative solution is to assign a version to the ClassLoader
+and then use dependencies. i.e. there will be mutliple versions of the same
+classes in different ClassLoaders that can be chosen using the dependency
+mechanism.
+This allows ClassLoaders that want to use the same version to share the classes.
+
+The consistency of the classes can also be checked at deployment time
+by the ClassLoading framework to ensure that applications that want to
+call each other by reference have the same class versions.
+
+GOALS OF THE JBOSS CLASSLOADER PROJECT
+
+The goals for the JBoss ClassLoader project come directly from the
+issues raised above and some logical extensions of these requirements.
+
+* Provide a simpler mechanism for plugging in ClassLoading rules without
+having to worry too much about the implementation or boiler plate details
+
+* Provide common features that a ClassLoader implementation can use
+
+* Allow differently implementated ClassLoaders to work together
+
+* Support peer delegation models including the JBoss UnifiedClassLoader
+and the OSGi models
+
+* Provide a versioning mechanism for ClassLoaders
+
+* Provide a pluggable dependency mechanism to resolve ClassLoading dependencies
+
+* Allow ClassLoaders to take part in the full ClassLoading infrastructure
+regardless of how they are constructed, i.e. whether they are constructed
+explicitly in POJO configuration or implicitly from spec defined rules
+
+* Allow the user to use only that part of the ClassLoading infrastructure
+as is required for their problem
+
+* Define a common mechanism for Class Annotation Scanning across ClassLoader
+implementations
Added: projects/docs/classloading/docs/02.abstractions.txt
===================================================================
--- projects/docs/classloading/docs/02.abstractions.txt (rev 0)
+++ projects/docs/classloading/docs/02.abstractions.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,66 @@
+ABSTRACTIONS - OVERVIEW
+
+The JBoss ClassLoader framework is made up of a number of abstractions
+at different levels. The details of these abstractions will be dealt with
+more thoroughly later in this documentation.
+
+The purpose of this section is give a high level overview of what
+each part of the framework does.
+
+JBOSS CLASSLOADER
+
+The purpose of the JBoss ClassLoader subproject is to provide the
+actual runtime ClassLoading mechanism.
+
+It provides the ClassLoader implementation, but this has largely
+been designed to be invisible.
+
+Instead people that want to write their own ClassLoader implementations
+will write a ClassLoaderPolicy which provides a simpler api for locating
+classes and resources and specifying other rules associated with
+the classloader.
+
+Direct users of this level of abstraction instantiate a
+ClassLoaderPolicy and register it with a ClassLoaderSystem
+to create a ClassLoader. They may also create ClassLoaderDomains to
+partition the ClassLoaderSystem.
+
+This layer also includes the implementation of things like the DelegateLoader
+model, classloading or resource filters and parent-child delegation polices.
+
+The runtime is JMX enabled to expose what exists, what policy is getting
+used for each classloader along with classloading statistics and debugging
+methods to help determine where things are loaded from.
+
+JBOSS CLASSLOADING
+
+The JBoss ClassLoading subproject is a higher level abstraction
+whose main role is to control ClassLoading dependencies.
+
+Users at this level instead of using the JBoss ClassLoader abstraction
+directly, will create ClassLoading Modules which include the ClassLoader's
+dependencies. Once the dependencies are specified the ClassLoader(Policy)s
+are constructed and wired together according to their dependencies.
+
+To facilitate this definition of a ClassLoader before it exists,
+the abstraction includes a ClassLoadingMetaData model.
+
+The ClassLoadingMetaData can be exposed as a "Managed Object"
+within the new JBoss5 profile service, allowing system admins to deal
+with the higher level policy details rather than the implementation details.
+
+JBOSS CLASSLOADING VFS
+
+The ClassLoading VFS subproject provides implementations of both
+of the above abstractions using the JBoss VFS project.
+
+It also includes a VFSClassLoaderFactory that can be used to easily
+create ClassLoading Modules within the JBoss Microcontainer.
+
+OTHERS
+
+The JBoss5 deployers framework makes use of the above abstractions
+to provide ClassLoading within JBossAS 5. For most users the default
+rules will make this invisble, but an understanding of the above
+abstractions will allow "power users" to take advantage of
+new features within JBoss5.
Added: projects/docs/classloading/docs/03.classloader.txt
===================================================================
--- projects/docs/classloading/docs/03.classloader.txt (rev 0)
+++ projects/docs/classloading/docs/03.classloader.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,98 @@
+JBOSS CLASSLOADER
+
+The JBoss ClassLoader has been designed with two different users
+in bind. The first group are those that want to use the framework
+to directly and easily construct ClassLoading topolgies, while the
+second group want to implement their own ClassLoading rules or mechanisms.
+
+DIRECT USERS
+
+An example of the first group would do something like:
+
+// Get a factory
+ClassLoaderSystem system = ClassLoaderSystem.getInstance();
+
+// Create a policy and configure it
+SomeClassLoaderPolicy policy = new SomeClassLoaderPolicy(...);
+policy.setSomeProperty(...);
+
+// Register the policy to create the classloader
+ClassLoader classLoader = system.registerClassLoaderPolicy(policy);
+
+They can construct as many classloaders as they like and specify how
+the ClassLoaders interrelate (if at all).
+
+POLICY IMPLEMENTORS
+
+The second group are interested in writing their own ClassLoading mechanisms.
+Rather than having to write a ClassLoader from scratch that can't interoperate
+with other ClassLoading mechanisms, they would write a ClassLoaderPolicy
+to define how classes and resources are located and what other policies
+are associated with them.
+
+To do this they extend the abstract ClassLoaderPolicy class
+and then override the parts they want to change, an
+simplistic example would look something like:
+
+public class MyClassLoaderPolicy extends ClassLoaderPolicy
+{
+ public URL getResource(String path)
+ {
+ // locate the resource or class
+ }
+
+ // other changes here
+}
+
+RATIONAL
+
+The advantage of this approach are that a lot of the hard work
+of implementing a classloader correctly in more complicated use
+cases are already solved.
+
+The policy writer is just involved in how classes and resources
+are found and other definitional aspects such as assigning protection
+domains.
+
+The direct user can take these policies and assemble them in
+different topologies such as parent-child or peer models,
+group the policies into different ClassLoaderDomains for partioning
+or apply filters to control what can be loaded or exported.
+
+In this way, the JBoss ClassLoader framework acts as the mediator
+between the two very different users.
+
+THE MAIN FRAMEWORK
+
+The framework is split into two different packages.
+org.jboss.classloader.spi
+org.jboss.classloader.spi.base
+
+The "base" package is intended to hide implementation details
+from the users and also avoids (un)intential changes that could
+break the framework.
+
+The main framework is made up of three classes.
+
+ClassLoaderSystem which serves as a factory (and repository)
+for the other two classes.
+ClassLoaderDomain which allows for partioning of the ClassLoadingSystem.
+ClassLoaderPolicy which is what describes a ClassLoader.
+
+The details of these classes will be described later.
+
+In addition to the above classes, there are some other
+important abstractions that are used in the framework.
+
+(Delegate)Loader which provides the core notion of loading a class or
+resource but typically is just a link to a real ClassLoader(Policy)
+with some extra rules such as filtering.
+
+PackageInformation which is used when assigning classes to packages.
+The most common case is to create this from information in a manifest
+which this class helps you do.
+
+ParentPolicy which describes whether parent delegation should be
+first or last or a mixture based on filters.
+
+ClassFilter which defines how classes or resources can be filtered.
Added: projects/docs/classloading/docs/10.defineClass.txt
===================================================================
--- projects/docs/classloading/docs/10.defineClass.txt (rev 0)
+++ projects/docs/classloading/docs/10.defineClass.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,68 @@
+DEFINING A CLASS
+
+It is worthwhile understanding what happens when you define class.
+
+Hopefully, this will make some sense out of some of the
+less obvious callbacks to the ClassLoaderPolicy.
+
+BYTE CODE
+
+When defining a class, the bytecode needs to be loaded.
+
+This step maps to
+
+ClassLoaderPolicy.getResourceAsStream()
+
+which by default invokes
+
+ClassLoaderPolicy.getResource()
+
+PROTECTION DOMAIN
+
+The class is (optionally) assigned to a ProtectionDomain which is a
+set of runtime permissions. The ProtectionDomain is also associated
+with a CodeSource which is usually the "root" of the class's location,
+e.g. the URL of the jar containing the class
+
+This step maps to
+
+ClassLoaderPolicy.getProtectionDomain()
+
+PACKAGE
+
+Each class is (optionally) assigned to a package. This information
+will probably come from a MANIFEST.MF file. The PackageInformation class
+has a helper method for populating the values from a Manifest.
+
+The code source location from the ProtectionDomain is also used when packages
+are Sealed. That is other ClassLoaders can't add classes to the package.
+
+This maps to
+
+CLassLoaderPolicy.getClassPackageInformation()
+
+NOTE: A package is only defined once and then only if some other
+ClassLoader visible from this ClassLoader has not already defined the
+package.
+
+TRANSFORMATION
+
+There is also a
+
+ClassLoaderPolicy.transform()
+
+invocation that is intended to support old mechanisms for byte
+code manipulation.
+By default this delegates through the ClassLoaderDomain to the
+ClassLoaderSystem to determine how the class should be transformed.
+This mechanism is redundant in recent JREs where the agent
+mechanism allows for "abitrary" byte code manipulation.
+
+CLASS DEFINITION
+
+Once the above work has been done. the native
+ClassLoader.defineClass()
+method is invoked. At this point the JRE will take
+over the definition of the class which besides
+validting the bytecode will likely cause further ClassLoading
+for things like the parent classes.
Added: projects/docs/classloading/docs/11.policy.txt
===================================================================
--- projects/docs/classloading/docs/11.policy.txt (rev 0)
+++ projects/docs/classloading/docs/11.policy.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,121 @@
+CLASSLOADER POLICY
+
+The org.jboss.classloader.spi.ClassLoaderPolicy
+abstract class is the mechanism to use when you want to write
+your own ClassLoading mechanism.
+
+Usually this will involve overridding the class definition
+methods but you can also override the other policy callbacks to
+change the behaviour.
+
+See VFSClassLoaderPolicy for a concrete implementation of this class
+using the JBoss VFS abstraction.
+
+LOADING RESOURCES AND CLASSES
+
+Classes and resources are found based on a path.
+The path is a string that looks something like:
+a/b/c/x.class
+
+The two methods you need to define are:
+
+URL getResource(String path);
+void getResources(String path, Set<URL> urls);
+
+The second method allows for classloading mechanisms that can have
+multiple roots where a specific resource path may be available in
+many of the roots. e.g. If the ClassLoader is made up of many jars,
+there will be many META-INF/MANIFEST.MF resources.
+You should just add each URL that exists to the "urls" Set.
+
+Additionally, you might want to override
+
+InputStream getResourceAsStream(String path);
+
+if you can do it more efficiently than the default mechanism which is
+url.openStream() from the result of getResource();
+
+OTHER POLICY
+
+The other callbacks fall into a number of groups. Some control
+how delegation works, others control caching and others control
+how classes are defined. You can always add other properties to your
+policies, such as additional filters or simpler rules for determing
+what gets exported, etc.
+
+NOTE: Many of these properties are really meant for external configuration
+by the users of your policy. It is your choice whether you support
+a specific feature or leave the default rules in place.
+
+NAME
+
+The getName() is intended for use in debugging
+such that the the ClassLoader can be easily identified.
+
+This will appear in the toString() of both the policy and the
+ClassLoader. There is an additional toLongString() method where
+you can add addtional information such as your own properties.
+
+OBJECT NAME
+
+For JMX management, each ClassLoader is assigned an ObjectName.
+By default this uses the getName() to construct it.
+
+EXPORTED PACKAGES
+
+The getPackagesNames() allows you to specify which packages
+should be considered exported when other ClassLoaders use you
+as a delegate.
+
+DELEGATES
+
+The getDelegates() determines which other policies are the
+"imports" or delegates of this policy. The delegates will be
+asked first whether they can load the class.
+Typically you will provide a mechanism for the user of the policy
+to set the list of delegates which will probably be a list of
+(Lazy)FilteredDelegateLoaders.
+
+IMPORT ALL
+
+The isImportAll() allows the policy to be configured such that
+it will import any exported class from a ClassLoaderPolicy in the
+same ClassLoaderDomain (or its parent domain).
+When this is true it mimics the behaviour of the UnifiedClassLoader (UCL).
+
+CACHEABLE/BLACKLISTABLE
+
+The isCachable()/isBlackListable() tells the ClassLoader framework
+whether it can cache the URLs returned from getResource()
+or null URLs in the case of blacklisting.
+NOTE: Classes are always cached by the JRE classloading mechanism
+while they remain unavailable for garbage collection.
+
+PROTECTION DOMAIN
+
+The getProtectionDomain(String className, String path) allows you to assign a
+java.security.ProtectionDomain to a class during class definition.
+
+PACKAGE INFORMATION
+
+The getPackageInformation(String packageName)
+and getClassPackageInformation(String className, String packageName)
+allow you to assign a class to a package.
+The PackageInformation class has helper methods for creating package
+information from a Manfiest.
+
+JDK REQUEST
+
+See JDKChecker.
+
+JMX INTERFACE
+
+When the ClassLoaderSystem is registered with an MBeanServer,
+the ClassLoader is also automatically registered.
+
+This includes viewing most of the policy mentioned above,
+which ClassLoaderDomain the ClassLoader belongs to, the toLongString()
+to see all details (including custom policy properties)
+to see information on the loaded classes and resources and
+any blacklisted resources and finally to determine which ClassLoader
+is used when starting a ClassLoading request from this ClassLoader.
Added: projects/docs/classloading/docs/12.system.txt
===================================================================
--- projects/docs/classloading/docs/12.system.txt (rev 0)
+++ projects/docs/classloading/docs/12.system.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,121 @@
+CLASSLOADER SYSTEM
+
+The ClassLoaderSystem serves as a factory repository for the other
+ClassLoading artefacts.
+
+SINGLETON
+
+You can have as many ClassLoaderSystems as you want, but the usual
+mechanism is to use the singleton obtained from
+
+ClassLoaderSystem.getInstance()
+
+DEFAULT IMPLEMENTATION
+
+If you want to change this singleton, you can specify the name
+of a class that extends ClassLoaderSystem using a system property.
+e.g. from the command line
+
+-Dorg.jboss.classloader.system,spi.ClassLoaderSystem=com.acme.MyCLSystem
+
+The class must also have a default constructor.
+
+The most obvious reason for overridding the ClassLoaderSystem implementation
+is to change the createDomain() method with a custom domain that overrides
+some of its callbacks.
+
+SECURITY
+
+The factory methods and ClassLoaderSystem instance retrieval
+are protected by the RuntimePermission("createClassLoader").
+This stops unauthorised classes changing the classloading when a
+SecurityManager is installed.
+
+CLASSLOADER SYSTEM SHUTDOWN
+
+If you want to stop the whole ClassLoadingSystem there is a
+ClassLoaderSystem.shutdown() this will remove all domains and classloaders
+and prevent any new ones getting constructed.
+
+NOTE: It would be unwise to do this with the singleton if you want
+to use it again.
+
+DOMAIN CONSTRUCTION
+
+The ClassLoaderSystem has a number of methods for managing ClassLaoderDomains.
+Many of them are overloaded for ease-of-use with the main method being
+
+ClassLoaderDomain createAndRegisterDomain(String name, ParentPolicy parentPolicy, Loader parent);
+
+If the parent is null then it will create a Loader based on the
+current Thread Context ClassLoader (TCL) such that the domain can
+access standard java system classloaders. This will also make
+other classes available from classloader unless you choose a parent policy
+to avoid this.
+
+NOTE: A ClassLoaderDomain is also a Loader so ClassLoaderDomains can be
+hierarchical.
+
+If the ParentPolicy is null it will use the BEFORE policy.
+The ParentPolicy is described in more detail elsewhere.
+
+CUSTOM DOMAIN IMPLEMENTATIONS
+
+To change the implementation of the ClassLoaderDomain you should
+override the ClassLoaderSystem class (see above) or create a custom
+ClassLoaderSystem and override the createDomain() method.
+
+DEFAULT DOMAIN
+
+There is a special domain called the "DefaultDomain" which always
+exists and can be retrieved using the getDefaultDomain() method.
+
+DOMAIN QUERIES
+
+The existing domains can be queried using
+isRegistered(String name)
+isDomainRegistered(ClassLoaderDomain)
+getDomain(String name)
+
+DOMAIN DESTRUCTION
+
+When you have finished with a domain you should
+unregisterDomain(ClassLoaderDomain)
+you can't unregister the DefaultDomain
+
+CLASSLOADER CONSTRUCTION
+
+There are also a number of methods for constructing ClassLoaders
+from ClassLoader policies, again this is for ease-of-use.
+Some of the methods include parameters for constructing Domains
+at the same time. They all eventually invoke:
+
+ClassLoader registerClassLoaderPolicy(ClassLoaderDomain domain, ClassLoaderPolicy policy)
+
+which registers a ClassLoaderPolicy with a domain and returns the
+cosntructed ClassLoader.
+
+If the domain is null it uses the DefaultDomain.
+
+CLASSLOADER DESTRUCTION
+
+Once you have finished with a ClassLoader you should unregister it:
+void unregisterClassLoaderPolicy(ClassLoaderPolicy policy)
+for ease of use there is also a
+void unregisterClassLoader(ClassLoader classLoader)
+so you don't have to remember the ClassLoaderPolicy.
+
+TRANSLATOR
+
+You can register a Translator with the ClassLoaderSystem
+which can perform bytecode manipulation. But with newer versions
+of java you should use the agent mechanism for this instead.
+
+JMX Interface
+
+If you register the ClassLoaderSystem with an MBeanServer then all
+the ClassLoaderDomains and ClassLoaders will automatically be
+registered and unregistered with the same MBeanServer as they are
+constructed/removed.
+The ClassLoaderSystem jmx interface provides a method to list
+the ClassLoaderDomain's ObjectNames.
Added: projects/docs/classloading/docs/13.domain.txt
===================================================================
--- projects/docs/classloading/docs/13.domain.txt (rev 0)
+++ projects/docs/classloading/docs/13.domain.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,54 @@
+CLASSLOADER DOMAIN
+
+There are a lot of implementation details to the ClassLoaderDomains.
+It is here where much of the policy rules are used.
+
+Most of this is hidden.
+
+If you want to override some of the callbacks then you override
+the createDomain() on the ClassLoaderSystem.
+
+The callbacks fall into two orthogonal groups.
+
+One group is defined by before/after behaviour, where the before is done
+before ClassLoading attempts within the domain and vice versa for the after.
+The other group differentiates attempts to load from the parent.
+
+The specific callbacks are:
+
+loadClass() - a classloading attempt
+findLoader() - find a loader for a class
+getResource() - attempt to find a resource or class
+getResources() - attempt to find mutliple resources
+getPackage() - find a package for the class
+getPackages() - find all packages visible from a classloader
+
+USE LOAD CLASS FROM PARENT
+
+The setUseLoadClassFromParent() complicates some of the above.
+
+Normally the ClassLoader Framework will use getResource() to try to
+find a class file to avoid locking ClassLoaders unnecessarily.
+However, when the parent is outside the ClassLoading framework
+e.g. the JRE's system classloader
+then this might fail to find to some classes.
+Instead it will fallback to the less efficient loadClass().
+
+So depending upon the parent you might see loadClassFromParent()
+or getResourceFromParent().
+
+setUseLoadClassFromParent(false) will make it consistent, but it
+is not the default.
+
+JMX INTERFACE
+
+When the ClassLoaderSystem is registered with an MBeanServer,
+the ClassLoaderDomain is also automatically registered.
+
+The JMX interface includes methods to see the domain name and parent
+domain name, the ClassLoaderSystem ObjectName to which it belongs,
+To list all the ClassLoaders in the domain.
+To retrieve information about which ClassLoaders export which package.
+To find which ClassLoader is getting used to load a class under
+"importAll" rules and to retrieve the URLs of resource paths
+within the domain.
Added: projects/docs/classloading/docs/14.parentPolicy.txt
===================================================================
--- projects/docs/classloading/docs/14.parentPolicy.txt (rev 0)
+++ projects/docs/classloading/docs/14.parentPolicy.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,29 @@
+PARENT POLICY
+
+The parent policy is used to determine how a ClassLoadingDomain
+interacts with its parent.
+
+The parent policy is basically a pair of ClassFilters, one
+that decides whether it should search the parent before looking in the
+ClassLoaderDomain and another for after looking in the ClassLoaderDomain.
+
+Four policies are provided by default.
+
+BEFORE - Always check the parent for all classes before trying the
+ClassLoaderDomain, this mimics standard classloading rules.
+
+AFTER - This is almost the reverse of BEFORE, but java.*
+classes are checked before looking in the domain.
+
+BEFORE_BUT_JAVA_ONLY - This is similar to BEFORE, but only java.* and javax.*
+classes are loaded from the parent
+
+AFTER_BUT_JAVA_BEFORE - This is similar to AFTER execpt that javax.*
+classes are also loaded the parent before the domain is checked.
+
+You can construct your policies by providing a couple of class filters.
+I would also recommend using the constructor with a description
+to make logging easier to read:
+
+ParentPolicy(ClassFilter beforeFilter, ClassFilter afterFilter, String description);
+
Added: projects/docs/classloading/docs/15.classFilter.txt
===================================================================
--- projects/docs/classloading/docs/15.classFilter.txt (rev 0)
+++ projects/docs/classloading/docs/15.classFilter.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,40 @@
+CLASS FILTERS
+
+The class filters allow you to specify whether classes, packages
+and resources get filtered.
+
+There most direct use is in the ParentPolicy and FilteredDelegateLoader,
+but you can also add them to your ClassLoaderPolicies.
+
+There are three main methods:
+
+Match a class name (i.e. dot notation)
+
+ boolean matchesClassName(String className);
+
+Match a resource path (i.e. path notation including .class on the end)
+
+ boolean matchesResourcePath(String resourcePath);
+
+Match a package name (dot notation without the final class name)
+
+ boolean matchesPackageName(String packageName);
+
+Some standard filters are provided in the ClassFilter class
+
+EVERYTHING - allow everything
+NOTHING - allow nothing
+NOTHING_BUT_JAVA - allow java.*
+JAVA_ONLY - allow java.* and javax.*
+
+There are few implementations of filters, but only the
+org.jboss.classloader.spi.filter.PackageClassFilter
+is currently in the supported api.
+This takes a list of package names to filter against.
+
+For other examples see:
+
+org.jboss.classloader.plugins.filter.PatternClassFilter using regular
+expressions.
+org.jboss.classloader.plugins.filter.CombiningClassFilter to implement
+AND/ORs from other filters.
Added: projects/docs/classloading/docs/16.JDKChecker.txt
===================================================================
--- projects/docs/classloading/docs/16.JDKChecker.txt (rev 0)
+++ projects/docs/classloading/docs/16.JDKChecker.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,30 @@
+JDK CHECKER
+
+Most users can ignore this section.
+
+It only applies when the ParentPolicy of the root ClassLoaderDomain
+is restricted to load only java.* and javax.* or similar.
+
+Some JREs assume that all their classes can be loaded from any classloader
+which is untrue with that ParentPolicy.
+An example might be sun.reflect.*
+
+The JDK Checker runs when it determines that all other mechanisms
+failed to load a class. It then decides whether the ClassLoading attempt
+was made outside the normal ClassLoading framework, i.e. by the JRE.
+
+If that is true then it will attempt to use the SystemClassLoader
+to load the class.
+
+If you need to change this mechanism, you can change it on the
+ClassLoaderPolicy, but more likely you can set a system property
+to change it globally, e.g.
+
+-Dorg.jboss.classloader.spi.jdk.JDKChecker=com.acme.MyChecker
+
+The class should implement the JDKChecker interface
+and have a default constructor.
+
+I'd recommend the class extends
+org.jboss.classloader.plugins.jdk.AbstractJDKChecker
+if you just want to add to the existing mechanism.
Added: projects/docs/classloading/docs/17.Loader.txt
===================================================================
--- projects/docs/classloading/docs/17.Loader.txt (rev 0)
+++ projects/docs/classloading/docs/17.Loader.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,31 @@
+LOADER
+
+Moving further towards the implementation details, the
+org.jboss.classloader.spi.Loader interface
+is used in the delegation mechanisms.
+
+Its most common external use is that a ClassLoaderDomain can take
+any Loader as a parent.
+
+DELEGATE LOADER
+
+The
+org.jboss.classloader.spi.DelegateLoader
+class extends the Loader interface to add the notion of
+ClassLoaderPolicy delegation.
+
+Although from a users point of view when they construct
+delegates they are delegating to ClassLoaderPolicys, in practice
+the ClassLoaderPolicy is only used as metadata to determine how
+the delegation should work. The reality is somewhat more complicated.
+
+For real uses cases, the delegates should either the
+org.jboss.classloader.spi.filter.FilteredDelegateLoader
+or
+org.jboss.classloader.spi.filter.LazyFilteredDelegateLoader
+which filter the delegation based on the exports of the ClassLoaderPolicy.
+
+The Lazy version allows you to pass a ClassLoaderPolicyFactory
+such that underlying delegate doesn't have to exist when you construct
+a ClassLoaderPolicy.
+This is most useful for breaking circular dependencies.
Added: projects/docs/classloading/docs/30.version.txt
===================================================================
--- projects/docs/classloading/docs/30.version.txt (rev 0)
+++ projects/docs/classloading/docs/30.version.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,65 @@
+VERSIONS
+
+Versions are used to allow resolution of dependencies based on
+VersionRanges.
+
+This section introduces the versioning scheme and its programmatic
+use. In practice most users will just specify the version
+constraints in some xml or a manifest defintion.
+
+VERSION
+
+The JBoss ClassLoading framework uses the same Versioning scheme
+as OSGi, i.e.
+major[.minor[.micro[.extension]]]
+where all components are treated alpha-numerically
+and [] means optional.
+
+This contains some gotchas such as;
+1.0.2 > 1.0.12
+or
+1.0.0.Final < 1.0.0.NotFinal
+
+Since the "versions" used throughout the framework are defined as
+Objects, you can also just pass the String representation
+rather than doing
+new Version("1.0.0")
+but that does mean it always has to convert it to a Version object
+for comparison which involves some validation and so is slightly slower.
+
+VERSION RANGE
+
+Version ranges consist of a lower and upper bound version and a
+boolean for each bound to decide whether the bound is inclusive
+or exclusive.
+
+By default the lower bound is inclusive and the upper bound is
+exclusive.
+
+Examples:
+
+new VersionRange("1.0.0"); // 1.0.0 <= version < infinity
+new VersionRange("1.0.0", "2.0.0"); // 1.0.0 <= version < 2.0.0
+new VersionRange("1.0.0", false, "2.0.0", true); // 1.0.0 < version <= 2.0.0
+
+VERSIONING SCHEMES
+
+Most users can probably ignore this first part.
+
+The notion of a version used in the ClassLoading framework
+is a little more general than that used in similar frameworks.
+
+The default implementation allows the use of a Version class
+or a String representation according to the OSGi version rules.
+
+But different version schemes can be used, by registering an
+org.jboss.classloading.spi.VersionComparator
+implementations with the
+org.jboss.classloading.spi.VersionComparatorRegistry
+
+i.e. if you know how to compare your version to an OSGi version
+than you could write a comparator for that.
+
+In practice, this only really becomes relevent when classloaders
+from one versioning scheme, e.g. an OSGi deployment want to import
+a none OSGi classloader or vice versa.
Added: projects/docs/classloading/docs/31.classloading.txt
===================================================================
--- projects/docs/classloading/docs/31.classloading.txt (rev 0)
+++ projects/docs/classloading/docs/31.classloading.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,38 @@
+CLASSLOADING
+
+DOMAINS
+
+The
+org.jboss.classloading.spi.dependency.ClassLoading
+and
+org.jboss.classloading.spi.dependency.Domain
+
+class are almost direct analogues of ClassLoaderSystem and ClassLoaderDomain.
+
+But instead of directly creating those artefacts they serve as placeholders
+for what will be constructed when the dependencies are satisifed.
+
+There are a few differences. Modules are registered directly with
+the ClassLoading registry without having to create the Domains explictly.
+The Modules expose metadata on which Domain they want to join.
+
+The Domains control the resolution process when looking for which
+other Modules might satisfy another Modules dependencies.
+Again, this is populated automatically from the Module's metadata.
+
+CLASSLOADING SPACE
+
+When not using the "importAll" strategy. Each module is assigned
+to a "ClassLoadingSpace" according to what other modules exports it
+depends upon.
+The purpose of the ClassLoadingSpace is to keep track of all
+dependencies that are related and to make sure they are consistent.
+
+e.g. if Module A wants to import only Module C version 1.2.3 and Module B
+wants to import only Module C 1.2.4 that is ok they are in different
+ClassLoadingSpaces.
+
+But if Module A decides it is going to import Module B they can't agree on
+a version of Module C to use.
+
+It is the ClassLoadingSpace that detects these inconsistencies.
Added: projects/docs/classloading/docs/32.module.txt
===================================================================
--- projects/docs/classloading/docs/32.module.txt (rev 0)
+++ projects/docs/classloading/docs/32.module.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,122 @@
+MODULE
+
+An org.jboss.classloading.spi.dependency.Module represents a proto classloader.
+It includes all the metadata required to create a classloader
+and dependencies required before it can do so.
+
+In practice, a subclass of the Module will determine which type
+of ClassLoaderPolicy gets constructed.
+
+NAME AND VERSION
+
+Each module has a name and version. If you don't specify the
+version it defaults to 0.0.0
+
+In addition you can give the module an "alias" called the
+"contextName" when the name and version is unwieldy
+or it depends upon file system specific details.
+
+CONFIGURATION
+
+The module provides metadata that control how the classloader gets constructed
+and its dependencies.
+
+NOTE: Not all modules will implement every configuration option.
+This will depend upon the underlying ClassLoaderPolicy implementation chosen.
+
+Below we list the "standard ones" but other modules may implement more
+(or less).
+
+(Parent) Domain
+
+The module provides information about which Domain and which
+Parent Domain it wants to join.
+
+Export All
+
+Whether all packages in the classloader should be exported
+(this is not the default).
+
+See export all.
+
+Included
+
+A filter of what packages should be included (nothing by default
+meaning it is ignored).
+
+Excluded
+
+A filter of what packages shouldn't be excluded (nothing by default
+meaning it is ignored).
+
+Excluded Export
+
+A filter of packages that should not be exported when using "export all".
+
+Import All
+
+Whether to import all exported packages in a domain, the default is false.
+
+j2seClassLoadingCompliance
+
+Whether to load parent first or last. The default is parent first, i.e. true.
+
+Cachable
+
+Whether resources can be cached, the default is true
+
+Blacklistable
+
+Whether resources can blacklisted (i.e. cache misses) the default is true.
+
+PackageNames
+
+The packages exported by this module
+
+Requirements
+
+The collection of dependencies required by this module, see Requirements
+
+Capabilities
+
+The collections of things this module provides that might satisfy
+dependencies see Capabilities.
+
+Dynamic ClassRoot
+
+A URL for storing runtime generated classes.
+
+DELEGATE
+
+The create(Lazy)DelegateLoader provide the hooks
+for constructing imported delegates.
+
+These are invoked from the get/addDelegates() methods
+that does most of the work.
+
+LIFECYCLE
+
+The release() method will be invoked when the Module is not required.
+Additionally, modules should implement the reset() method to
+avoid holding references that might stop the garbage collector
+from working properly or remove any caching that might cause a redeployment
+to use old data.
+
+VISIT
+
+See resource visitor.
+
+
+SUBCLASSES
+
+Two useful subclasses are provided to flesh a lot of the details.
+org.jboss.classloading.spi.dependency.helpers.ClassLoadingMetaDataModule
+delegates most of the policy decisions to a ClassLoadingMetaData object.
+
+org.jboss.classloading.spi.dependency.helpers.ClassLoadingPolicyModule
+extends that class to add support for constructing ClassLoaderPolicys
+for both the main classloader for this module and referencing them
+for the delegates.
+
+In the later case, you just have to implement determinePolicy()
+to create the ClassLoaderPolicy implementation you want.
Added: projects/docs/classloading/docs/33.metadata.txt
===================================================================
--- projects/docs/classloading/docs/33.metadata.txt (rev 0)
+++ projects/docs/classloading/docs/33.metadata.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,60 @@
+CLASSLOADING METADATA
+
+The ClassLoading metadata just contains the config options
+of a Module. As such it is ClassLoaderPolicy neutral.
+
+(Parent) Domain
+
+The module provides information about which Domain and which
+Parent Domain it wants to join.
+
+Export All
+
+Whether all packages in the classloader should be exported
+(this is not the default).
+
+See export all.
+
+Included(Packages)
+
+A filter of what packages should be included (nothing by default
+meaning it is ignored).
+
+Excluded(Packages)
+
+A filter of what packages shouldn't be excluded (nothing by default
+meaning it is ignored).
+
+ExcludedExport(Packages)
+
+A filter of packages that should not be exported when using "export all".
+
+Import All
+
+Whether to import all exported packages in a domain, the default is false.
+
+j2seClassLoadingCompliance
+
+Whether to load parent first or last. The default is parent first, i.e. true.
+
+Cachable
+
+Whether resources can be cached, the default is true
+
+Blacklistable
+
+Whether resources can blacklisted (i.e. cache misses) the default is true.
+
+Requirements
+
+The collection of dependencies required by this module, see Requirements
+
+Capabilities
+
+The collections of things this module provides that might satisfy
+dependencies see Capabilities.
+
+MANAGEMENT
+
+The ClassLoadingMetaData is a "ManagedObject" meaning it can
+be understood by the profile service and its clients.
Added: projects/docs/classloading/docs/34.exportall.txt
===================================================================
--- projects/docs/classloading/docs/34.exportall.txt (rev 0)
+++ projects/docs/classloading/docs/34.exportall.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,14 @@
+EXPORT ALL
+
+The Export All configuration option is a convenience mechanism
+when you want to export everything from a classloader.
+
+Valid values are
+
+ExportAll.ALL - Export everything
+ExportAll.NON_EMPTY - Only export non-empty packages.
+
+It can be further refined by the ExcludedExport filter.
+
+NOTE: These configurations are ignored when you explictly state
+capabilities.
Added: projects/docs/classloading/docs/35.capabilities.txt
===================================================================
--- projects/docs/classloading/docs/35.capabilities.txt (rev 0)
+++ projects/docs/classloading/docs/35.capabilities.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,38 @@
+CAPABILITES
+
+Capabilities are what this module provides.
+
+Typically they define a module name and version plus package names and version,
+but capabilities can be anything you define.
+
+When a version is not specified, the version of the module is used.
+
+DEFAULT CAPABILITIES
+
+Additionally when you don't specify capabilities, a module capability
+is constructed from the module name and version and package
+capabilities are constructed from the exported packages.
+
+But if you explicitly specify capabilities, none of this is done.
+
+STANDARD CAPABILITIES
+
+The org.jboss.classloading.spi.metadata.ClassLoadingMetaDataFactory
+can be used to construct standard capabilities, these include:
+
+createModule - a module capability
+createPackage - a package capability
+
+USER DEFINED
+
+Anything that implements
+org.jboss.classloading.spi.metadata.Capability
+can be added to a Module's or ClassLoadingMetaData's capabilities.
+
+If you want your Capability to be able to add exported packages
+to the Classloader then it should also implemetn
+org.jboss.classloading.spi.metadata.ExportPackages
+
+The
+org.jboss.classloading.spi.metadata.helpers.AbstractCapability
+class is available to help you implement a capability.
Added: projects/docs/classloading/docs/36.requirements.txt
===================================================================
--- projects/docs/classloading/docs/36.requirements.txt (rev 0)
+++ projects/docs/classloading/docs/36.requirements.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,72 @@
+REQUIREMENTS
+
+Requirements are the module's dependencies.
+
+Typically they define a module or package name and version range
+but requirements can be anything you define.
+
+When a version range is not specified, every version is assumed.
+
+In addition a requirement can other properties
+
+isReExport - whether this requirement should be included in the importing
+classloader's capabilities
+
+wantsReexports - whether this dependency should also include re-exports
+of other classloaders
+
+optional - whether the requirement is optional
+
+dyanamic - like optional except the dependency can be resolved at runtime
+
+DEFAULT REQUIREMENTS
+
+There are no default requirements
+
+STANDARD REQUIREMENTS
+
+The org.jboss.classloading.spi.metadata.ClassLoadingMetaDataFactory
+can be used to construct standard requirements, these include:
+
+requireModule - dependency on another module
+reexportModule - a requireModule that re-exports the module requirement
+requirePackage - dependency on another package
+reexportPackage - a requirePackage that re-exports the package requirement
+usesPackage - a requirePackage that is optional
+
+USER DEFINED
+
+Anything that implements
+org.jboss.classloading.spi.metadata.Requirement
+can be added to a Module's or ClassLoadingMetaData's requirements.
+
+The
+org.jboss.classloading.spi.metadata.helpers.AbstractRequirement
+class is available to help you implement a requirement.
+
+CONSISTENCY
+
+To enable consistency checking a Requirement implement the
+isConsistent(Requirement) method to decide whether it will conflict
+with another requirement.
+
+REQUIREMENTS DEPENDENCY ITEM
+
+Most users will not be concerned with this section.
+
+If you do implement your requirement/capability and discover that the
+
+ boolean resolves(Module module, Requirement requirement);
+
+method on the Capability is not enough to do what you want,
+the class
+org.jboss.classloading.spi.dependency.RequirementsDependencyItem
+has been made a part of the supported api.
+
+Although this is really an implementation detail, you should be able
+to resolve more difficult problems by extending this class
+and modifying your Module class to use the subclass.
+
+WARNING: If do find your are doing this, report the issue.
+This implementation detail is likely to be deprecated and "removed" in
+future versions.
Added: projects/docs/classloading/docs/37.resourceVisitor.txt
===================================================================
--- projects/docs/classloading/docs/37.resourceVisitor.txt (rev 0)
+++ projects/docs/classloading/docs/37.resourceVisitor.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,37 @@
+RESOURCE VISITOR
+
+The resource visitor is an additional api on the Module.
+
+void visit(ResourceVisitor visitor, ResourceFilter filter, ResourceFilter recurseFilter)
+void visit(ResourceVisitor visitor, ResourceFilter filter, ResourceFilter recurseFilter, URL... urls)
+
+You can provide a resource visitor and some filters to decide
+what you want to visit.
+
+The filter decides whether to visit a particular resource while the
+recusrseFilter decides whether to visit a "directory".
+
+The filter can also be specified on the Visitor itself.
+
+The "urls" is for when there are many roots (e.g. many jars) to a classloader
+and you just want to visit a subset of them.
+
+CLASS VISITOR
+
+This is a special case of the ResourceVisitor that only visits classes.
+The primary purpose of the ResourceVisitor api is for Class discovery
+such that annotations can be scanned instead of reading metadata from xml files.
+
+RESOURCE CONTEXT
+
+The resource context which is given on every visit of a resource
+includes the classloader constructed from the module, the URL of the resource,
+the resource name, the "class name" i.e. the resource in dot notation
+if it is a class which you can check from isClass() and some helper methods
+to get the underlying resource as a stream or bytes or get the class if it is one.
+
+MODULE IMPLEMENTATION DETAILS
+
+It is upto the Module implementation whether it can support resource visiting.
+e.g. it would be impossible to visit a classloader's classes when they
+are defined by a http:// url since the contents cannot be listed.
Added: projects/docs/classloading/docs/40.xml.txt
===================================================================
--- projects/docs/classloading/docs/40.xml.txt (rev 0)
+++ projects/docs/classloading/docs/40.xml.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,216 @@
+XML for classloading metadata
+
+DEPLOYERS
+
+Within the jboss deployers framework you can add a
+META-INF/jboss-classloading.xml
+
+MICROCONTAINER
+
+Within the microcontainer you can also construct vfs classloaders
+using similar xml
+
+DIFFERENCE
+
+The key differences are the root element and xml namespaces are different.
+
+For the deployers it is
+
+<classloading name="test" version="1.0.0" export-all="ALL"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+For the microcontainer it is
+
+<classloader name="test" version="1.0.0" export-all="ALL"
+ xmlns="urn:jboss:classloader:1.0"/>
+
+The microcontainer also contains extra <root/> elements to define
+the vfs roots. The microcontainer version will be described
+elsewhere but the xml is very similar. This section assumes
+the deployer version.
+
+CLASSLOADING METADATA
+
+The xml files basically let you construct ClassLoadingMetaData
+from the xml. As such the options will look very similar to what is described
+there.
+
+Name and version
+
+The name and version are both optional in the deployers.
+The name will default to the deployment name while the version will default
+to 0.0.0
+
+<classloading name="test" version="1.0.0"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+(Parent) Domain
+
+The domain and parent domain are specified on the classloading element.
+The "DefaultDomain" is the default parent domain when the domain
+itself the "DefaultDomain".
+
+<classloading domain="MyDomain" parent-domain="DefaultDomain"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+Export All
+
+Whether all packages in the classloader should be exported
+(this is not the default).
+
+<classloading export-all="NON_EMPTY"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+See export all.
+
+Included
+
+A comma seperated list of package names to be included in the classloader
+
+<classloading included="com.acme.foo,com.acme.bar"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+Excluded(Packages)
+
+A comma seperated list of package names to be excluded from the classloader
+
+<classloading excluded="com.acme.foo,com.acme.bar"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+ExcludedExport(Packages)
+
+A comma seperated list of package names to be excluded from the exports
+
+<classloading export-all="ALL" excluded="com.acme.foo,com.acme.bar"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+Import All
+
+Whether to import all exported packages in a domain, the default is false.
+
+<classloading importAll="true"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+j2seClassLoadingCompliance
+
+Whether to load parent first or last. The default is parent first, i.e. true.
+
+<classloading parent-first="true"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+Cachable
+
+Whether resources can be cached, the default is true
+
+<classloading cache="false"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+Blacklistable
+
+Whether resources can blacklisted (i.e. cache misses) the default is true.
+
+<classloading blacklist="false"
+ xmlns="urn:jboss:classloading:1.0"/>
+
+Module Capabilitiy
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <capabilities>
+ <module name="Foo" version="1.0"/>
+ </capabilities>
+</classloading>
+
+Package Capabilities
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <capabilities>
+ <package name="com.acme.foo" version="1.0"/>
+ <package name="com.acme.bar" version="1.0"/>
+ </capabilities>
+</classloading>
+
+Require Module
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <module name="Another" fromVersion="1.0"/>
+ </requirements>
+</classloading>
+
+Require Package
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <package name="com.acme.foo" fromVersion="1.0"/>
+ </requirements>
+</classloading>
+
+Uses Package
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <uses name="com.acme.foo" fromVersion="1.0"/>
+ </requirements>
+</classloading>
+
+Specifying version ranges
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <package name="com.acme.foo" fromVersion="1.0" from-inclusive="true" toVersion="2.0" to-inclusive="false"/>
+ </requirements>
+</classloading>
+
+or a single version
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <package name="com.acme.foo" version="1.0"/>
+ </requirements>
+</classloading>
+
+Optional dependency
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <package name="com.acme.foo" version="1.0" optional="true"/>
+ </requirements>
+</classloading>
+
+Re-export dependency
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <package name="com.acme.foo" version="1.0" re-export="true"/>
+ </requirements>
+</classloading>
+
+Dynamic dependency
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <requirements>
+ <package name="com.acme.foo" version="1.0" dynamic="true"/>
+ </requirements>
+</classloading>
+
+User defined Requirements and Capabilities
+
+You can also include user defined requirements and capabilities
+provided that JBossXB knows how to unmarshal them
+
+This will typically require marking up your class with JAXB annotations
+and registering your class against a user defined namespace with JBossXB.
+
+Then you can do
+
+<classloading xmlns="urn:jboss:classloading:1.0">
+ <capabilities>
+ <my-capability xmlns="urn:com:acme:namespace:1.0" name="bar"/>
+ </capabilities>
+ <requirements>
+ <my-requirement xmlns="urn:com:acme:namespace:1.0" name="foo"/>
+ </requirements>
+</classloading>
+
+This works provided JBossXB knows how to unmarshall the xml
+into the relevant Requirement and Capability implementations.
Added: projects/docs/classloading/docs/99.glossary.txt
===================================================================
--- projects/docs/classloading/docs/99.glossary.txt (rev 0)
+++ projects/docs/classloading/docs/99.glossary.txt 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,64 @@
+Call-by-reference - the standard java calling convention
+
+Call-by-value - the calling convention used between JavaEE applications
+where different applications don't have direct references to each
+other classes.
+
+Class - The JVM bytecode and reflection information (not necessarily built
+from java source code)
+
+ClassLoader - The JRE mechanism used to locate, define and validate classes
+and load other resources
+
+ClassLoaderDomain - A parition of the ClassLoaderSystem
+
+ClassLoadingMetaData - An implementation neutral definition of the policy
+for a ClassLoader and what dependencies it requires.
+
+ClassLoadingModule - An abstraction of a ClassLoader(Policy) before it is
+constructed that includes the ClassLoader's dependencies
+
+ClassLoaderPolicy - The JBoss ClassLoader abstraction that allows users
+to define their own ClassLoading mechanisms
+
+ClassLoaderSystem - The main factory object for ClassLoaderDomains
+and creating ClassLoaders from ClassLoaderPolicys.
+
+ClassPath - A simple classloader that can be used to define from the
+command line
+
+CodeSource - Implements the notion that a class comes from a logical URL and
+associated signatures/certificates against which permissions can be assigned.
+
+DelegateLoader - Something that a ClassLoader can delegate to to load
+classes and resources
+
+JRE - Java Runtime Environment - The spec defined classes and supporting
+tools that make the JVM into a full java implementation
+
+JVM - Java Virtual Machine - The engine for running java bytecode
+
+Loader - The basic class and resource loading abstraction
+
+OSGi - TODO reference?
+
+Package - Each class is assigned to a package. Its most direct use is to
+allow private package access.
+
+ParentPolicy - Controls what and when classloading attempts should be
+delegated to the parent of a domain.
+
+Policy - see ClassLoaderPolicy
+
+ProtectionDomain - An ecapsulating of the code source, runtime permissions and
+digital signatures/certificates for a class or group of classes.
+
+TCL - The Thread Context ClassLoader. Each thread can be assigned a ClassLoader
+which most frameworks will use when making a dynamic classloading request.
+
+UCL - See UnifiedClassLoader
+
+UnifiedClassLoader - the legacy JBoss ClassLoading implementation used from
+JBossAS 3.0.0 through 4.x
+
+VFS - Virtual File System
Added: projects/docs/classloading/examples/pom.xml
===================================================================
--- projects/docs/classloading/examples/pom.xml (rev 0)
+++ projects/docs/classloading/examples/pom.xml 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,186 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>org.jboss</groupId>
+ <artifactId>jboss-parent</artifactId>
+ <version>4</version>
+ </parent>
+ <groupId>org.jboss.example.classloader</groupId>
+ <artifactId>jboss-classloader-example</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <packaging>pom</packaging>
+ <name>JBoss ClassLoader Example Parent POM</name>
+ <url>http://www.jboss.com/products/jbossmc</url>
+ <description>
+ JBoss ClassLoader Examples
+ </description>
+ <scm>
+ <connection>scm:svn:http://anonsvn.jboss.org/repos/jbossas/projects/docs/classloader/examples/trunk/</connection>
+ <developerConnection>scm:svn:https://svn.jboss.org/repos/jbossas/projects/docs/classloader/examples/trunk/</developerConnection>
+ <url>http://viewvc.jboss.org/cgi-bin/viewvc.cgi/jbossas/projects/docs/classloader/examples/trunk/</url>
+ </scm>
+
+ <modules>
+ <module>common-a</module>
+ </modules>
+
+ <properties>
+ <version.jboss.classloader>2.0.0.CR2</version.jboss.classloader>
+ </properties>
+
+ <build>
+ <finalName>${artifactId}</finalName>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>2.0.2</version>
+ <configuration>
+ <source>1.5</source>
+ <target>1.5</target>
+ <showDeprecation>true</showDeprecation>
+ <showWarnings>true</showWarnings>
+ <optimize>true</optimize>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-release-plugin</artifactId>
+ <version>2.0-beta-7</version>
+ <configuration>
+ <generateReleasePoms>false</generateReleasePoms>
+ <tagBase>https://svn.jboss.org/repos/jbossas/projects/docs/classloader/examples/tags</tagBase>
+ <autoVersionSubmodules>true</autoVersionSubmodules>
+ </configuration>
+ </plugin>
+ </plugins>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>make-assembly</id>
+ <phase>package</phase>
+ <goals>
+ <goal>attached</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <artifactId>maven-idea-plugin</artifactId>
+ <configuration>
+ <downloadSources>true</downloadSources>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <version>2.2</version>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>2.4.1</version>
+ <configuration>
+ <redirectTestOutputToFile>true</redirectTestOutputToFile>
+ <!--testFailureIgnore>true</testFailureIgnore-->
+ <includes>
+ <include>org/jboss/test/**/*TestCase.java</include>
+ </includes>
+ </configuration>
+ </plugin>
+ <plugin>
+ <!-- Configure javadoc plugin with APIviz -->
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <configuration>
+ <doclet>net.gleamynode.apiviz.APIviz</doclet>
+ <docletArtifact>
+ <groupId>net.gleamynode.apiviz</groupId>
+ <artifactId>apiviz</artifactId>
+ <version>1.1.0</version>
+ </docletArtifact>
+ <encoding>UTF-8</encoding>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ </build>
+
+ <repositories>
+ <repository>
+ <id>repository.jboss.org</id>
+ <name>JBoss Repository</name>
+ <layout>default</layout>
+ <url>http://repository.jboss.org/maven2/</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ <repository>
+ <id>snapshots.jboss.org</id>
+ <name>JBoss Snapshots Repository</name>
+ <layout>default</layout>
+ <url>http://snapshots.jboss.org/maven2/</url>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ </repository>
+ <!-- APIviz repository -->
+ <repository>
+ <id>apiviz.release</id>
+ <name>APIviz releases</name>
+ <url>http://apiviz.googlecode.com/svn/site/repo/mvn/release</url>
+ <releases>
+ <enabled>true</enabled>
+ </releases>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ </repositories>
+
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <reportSets>
+ <reportSet>
+ <reports>
+ <report>dependencies</report>
+ <report>issue-tracking</report>
+ <report>license</report>
+ <report>scm</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>findbugs-maven-plugin</artifactId>
+ <version>1.0.0</version>
+ </plugin>
+ </plugins>
+ </reporting>
+
+ <dependencyManagement>
+ <!-- The parent pom manages the inter-dependencies of the modules. -->
+ <dependencies>
+
+ <dependency>
+ <groupId>org.jboss.cl</groupId>
+ <artifactId>jboss-classloader</artifactId>
+ <version>${version.jboss.classloader}</version>
+ </dependency>
+
+ </dependencies>
+ </dependencyManagement>
+
+</project>
Added: projects/docs/classloading/svn-commit.tmp
===================================================================
--- projects/docs/classloading/svn-commit.tmp (rev 0)
+++ projects/docs/classloading/svn-commit.tmp 2010-01-19 23:13:09 UTC (rev 99620)
@@ -0,0 +1,4 @@
+Importing raw classloader documentation.
+--This line, and those below, will be ignored--
+
+A .
More information about the jboss-cvs-commits
mailing list