add documentation

Author: kwin

pom.xml

@@ -207,7 +207,7 @@
               <report>summary</report>
               <report>index</report>
               <report>dependencies</report>
-              <report>issue-tracking</report>
+              <report>issue-management</report>
               <report>scm</report>
             </reports>
           </reportSet>

src/main/java/org/codehaus/plexus/classworlds/ClassWorld.java

@@ -23,7 +23,7 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
-import java.util.Set;
+import java.util.function.Predicate;
 
 import org.codehaus.plexus.classworlds.realm.ClassRealm;
 import org.codehaus.plexus.classworlds.realm.DuplicateRealmException;
@@ -69,37 +69,37 @@ public ClassRealm newRealm( String id )
     public ClassRealm newRealm( String id, ClassLoader classLoader )
         throws DuplicateRealmException
     {
-        return newRealm( id, classLoader, Collections.emptySet() );
+        return newRealm( id, classLoader, null );
     }
 
     /**
-     * Shortcut for {@link #newRealm(String, ClassLoader, Set)} with the class loader of the current class.
+     * Shortcut for {@link #newRealm(String, ClassLoader, Predicate)} with the class loader of the current class.
      * @param id The identifier for this realm, must not be <code>null</code>.
-     * @param allowedResourceNamePrefixes the prefixes of resource names which should be exposed. Separator '/' is used here (even for classes).
+     * @param filter a predicate to apply to each resource name to determine if it should be loaded through this class loader
      * @return the created class realm
      * @throws DuplicateRealmException in case a realm with the given id does already exist
      * @since 2.7.0
      * @see FilteredClassRealm
      */
-    public synchronized ClassRealm newRealm( String id, Set<String> allowedResourceNamePrefixes )
+    public synchronized ClassRealm newRealm( String id, Predicate<String> filter )
          throws DuplicateRealmException
     {
-        return newRealm( id, getClass().getClassLoader(), allowedResourceNamePrefixes );
+        return newRealm( id, getClass().getClassLoader(), filter );
     }
 
     /**
      * Adds a class realm with filtering.
-     * Only resources/classes starting with one of the given prefixes are exposed.
+     * Only resources/classes whose name matches a given predicate are exposed.
      * @param id The identifier for this realm, must not be <code>null</code>.
      * @param classLoader The base class loader for this realm, may be <code>null</code> to use the bootstrap class
      *            loader.
-     * @param allowedResourceNamePrefixes the prefixes of resource names which should be exposed. Separator '/' is used here (even for classes).
+     * @param filter a predicate to apply to each resource name to determine if it should be loaded through this class loader
      * @return the created class realm
      * @throws DuplicateRealmException in case a realm with the given id does already exist
      * @since 2.7.0
      * @see FilteredClassRealm
      */
-    public synchronized ClassRealm newRealm( String id, ClassLoader classLoader, Set<String> allowedResourceNamePrefixes )
+    public synchronized ClassRealm newRealm( String id, ClassLoader classLoader, Predicate<String> filter )
         throws DuplicateRealmException
     {
         if ( realms.containsKey( id ) )
@@ -109,13 +109,13 @@ public synchronized ClassRealm newRealm( String id, ClassLoader classLoader, Set
 
         ClassRealm realm;
 
-        if ( allowedResourceNamePrefixes.isEmpty() )
+        if ( filter == null )
         {
             realm = new ClassRealm( this, id, classLoader );
         }
         else
         {
-            realm = new FilteredClassRealm( allowedResourceNamePrefixes, this, id, classLoader );
+            realm = new FilteredClassRealm( filter, this, id, classLoader );
         }
         realms.put( id, realm );
 

src/main/java/org/codehaus/plexus/classworlds/realm/FilteredClassRealm.java

@@ -22,7 +22,7 @@
 import java.net.URL;
 import java.util.Collections;
 import java.util.Enumeration;
-import java.util.Set;
+import java.util.function.Predicate;
 
 import org.codehaus.plexus.classworlds.ClassWorld;
 
@@ -32,31 +32,29 @@
  */
 public class FilteredClassRealm extends ClassRealm
 {
-
-    // no regular expressions for performance reasons
-    private final Set<String> allowedResourceNamePrefixes;
+    private final Predicate<String> filter;
 
     /**
      * Creates a new class realm.
      *
-     * @param allowedResourceNamePrefixes all resources not starting with one of the given prefixes are never exposed through this class loader
+     * @param filter a predicate to apply to each resource name to determine if it should be loaded through this class loader
      * @param world The class world this realm belongs to, must not be <code>null</code>.
      * @param id The identifier for this realm, must not be <code>null</code>.
      * @param baseClassLoader The base class loader for this realm, may be <code>null</code> to use the bootstrap class
      *            loader.
      */
-    public FilteredClassRealm( Set<String> allowedResourceNamePrefixes, ClassWorld world, String id, ClassLoader baseClassLoader )
+    public FilteredClassRealm( Predicate<String> filter, ClassWorld world, String id, ClassLoader baseClassLoader )
     {
         super( world, id, baseClassLoader );
-        this.allowedResourceNamePrefixes = allowedResourceNamePrefixes;
+        this.filter = filter;
     }
 
     @Override
     protected Class<?> findClassInternal( String name )
         throws ClassNotFoundException
     {
         String resourceName = name.replace( '.', '/' ).concat( ".class" );
-        if ( !isAllowedName( resourceName ))
+        if ( !filter.test( resourceName ) )
         {
             throw new ClassNotFoundException(name);
         }
@@ -66,7 +64,7 @@ protected Class<?> findClassInternal( String name )
     @Override
     public URL findResource( String name )
     {
-        if ( !isAllowedName( name ))
+        if ( !filter.test( name ) )
         {
             return null;
         }
@@ -77,15 +75,10 @@ public URL findResource( String name )
     public Enumeration<URL> findResources( String name )
         throws IOException
     {
-        if ( !isAllowedName( name ))
+        if ( !filter.test( name ) )
         {
             return Collections.emptyEnumeration();
         }
         return super.findResources( name );
     }
-
-    private boolean isAllowedName( String name )
-    {
-        return allowedResourceNamePrefixes.stream().anyMatch( name::startsWith );
-    }
 }

src/site/xdoc/apiusage.xml

@@ -32,7 +32,7 @@ ClassWorld world = new ClassWorld();
     <p>
     Once a <code>ClassWorld</code> is created, realms within it
     can be created.  These realms effectively only allow loading
-    of the core JVM classes.  
+    of the core JVM classes initially.
     </p>
 
 <source><![CDATA[
@@ -42,15 +42,21 @@ ClassRealm logComponentRealm = world.newRealm( "logComponent" );
 ]]></source>
 
     <p>
-    In order to make each <code>ClassRealm</code> useful, constituent
-    must be added to that each can provide certain classes.
+    In order to make each <code>ClassRealm</code> useful, constituents
+    in form of URLs must be added to it where each can provide certain classes.
+    The URL must return either a JAR or a directory on the default file system.
     </p>
 
 <source><![CDATA[
 containerRealm.addURL( containerJarUrl );
 logComponentRealm.addURL( logComponentJarUrl );
 ]]></source>
 
+    <p>
+    <code>ClassRealm</code>s can optionally be filtered to further restrict which classes/resources
+    are exposed. The filter is provided as additional argument to <code>world.newRealm( "filteredcontainer", myPredicate );</code>
+    </p>
+    
     <p>
     Now, links between the various realms need to be created to allow
     classes loaded from one to be available to classes loaded in another.

src/test/java/org/codehaus/plexus/classworlds/realm/FilteredClassRealmTest.java

@@ -19,9 +19,9 @@
 package org.codehaus.plexus.classworlds.realm;
 
 import java.io.IOException;
-import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
+import java.util.function.Predicate;
 
 import org.codehaus.plexus.classworlds.AbstractClassWorldsTestCase;
 import org.codehaus.plexus.classworlds.ClassWorld;
@@ -47,7 +47,7 @@ public void setUp() throws DuplicateRealmException
         Set<String> allowedResourcePrefixes = new HashSet<>();
         allowedResourcePrefixes.add( "a." );
         allowedResourcePrefixes.add( "a/Aa" );
-        realmA = this.world.newRealm( "realmA",  allowedResourcePrefixes );
+        realmA = this.world.newRealm( "realmA", s -> allowedResourcePrefixes.stream().anyMatch( s::startsWith ) );
     }
 
     @Test
@@ -78,7 +78,7 @@ public void testLoadClass() throws ClassNotFoundException
     @Test
     public void testLoadClassWithModule() throws IOException
     {
-        try (ExtendedFilteredClassRealm realmA = new ExtendedFilteredClassRealm( world, Collections.singleton( "a/Aa" ) )) {
+        try ( ExtendedFilteredClassRealm realmA = new ExtendedFilteredClassRealm( world, s -> s.startsWith( "a/Aa" ) ) ) {
             realmA.addURL( getJarUrl( "a.jar" ) );
             assertNotNull( realmA.simulateLoadClassFromModule( "a.Aa" ) );
             assertNull( realmA.simulateLoadClassFromModule( "a.A" ) );
@@ -94,9 +94,9 @@ public void testLoadClassWithModule() throws IOException
     static class ExtendedFilteredClassRealm extends FilteredClassRealm
     {
 
-        public ExtendedFilteredClassRealm( final ClassWorld world, Set<String> allowedResourcePrefixes )
+        public ExtendedFilteredClassRealm( final ClassWorld world, Predicate<String> filter )
         {
-            super( allowedResourcePrefixes, world, "java9", Thread.currentThread().getContextClassLoader() );
+            super( filter, world, "java9", Thread.currentThread().getContextClassLoader() );
         }
 
         public Class<?> simulateLoadClassFromModule(final String name)