[jboss-svn-commits] JBoss Common SVN: r4442 - in shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api: asset and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue May 25 14:23:22 EDT 2010
Author: ALRubinger
Date: 2010-05-25 14:23:20 -0400 (Tue, 25 May 2010)
New Revision: 4442
Modified:
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Archive.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchiveFactory.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchivePath.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Assignable.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filter.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filters.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/IllegalArchivePathException.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Node.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/SecurityActions.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/Asset.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayAsset.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayIOUtil.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/EmptyAsset.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/FileAsset.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/SecurityActions.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/StringAsset.java
shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/UrlAsset.java
Log:
[SHRINKWRAP-172] API cleanup and JavaDoc enhancements
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Archive.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Archive.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Archive.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -23,10 +23,24 @@
import org.jboss.shrinkwrap.api.formatter.Formatters;
/**
- * Archive
+ * Represents a collection of resources which may
+ * be constructed programmatically. In effect this
+ * represents a virtual filesystem.
*
- * Represents a collection of resources which may
- * be constructed declaratively / programmatically.
+ * <br /><br />All {@link Archive}
+ * types support the addition of {@link Node}s
+ * under a designated {@link ArchivePath} (context). The
+ * contents of a {@link Node} are either a directory
+ * or {@link Asset}.
+ *
+ * <br /><br />{@link Archive}s are generally created
+ * via an {@link ArchiveFactory} or via the default configuration
+ * shortcut {@link ShrinkWrap} utility class.
+ *
+ * <br /><br />Because {@link Archive}s are {@link Assignable},
+ * they may be wrapped in another user "view" used to perform
+ * operations like adding JavaEE Spec-specific resources
+ * or exporting in ZIP format.
*
* @author <a href="mailto:andrew.rubinger at jboss.org">ALR</a>
* @version $Revision: $
@@ -78,7 +92,7 @@
* @throws IllegalArchivePathException If the target is invalid.
*/
T add(Asset asset, String target) throws IllegalArgumentException;
-
+
/**
* Adds the specified directory.
*
@@ -225,7 +239,7 @@
* @throws IllegalArgumentException If the path or existing archive is not specified
*/
T merge(Archive<?> source, ArchivePath path, Filter<ArchivePath> filter) throws IllegalArgumentException;
-
+
/**
* Acts as a shorthand for {@link Archive#toString(Formatter)}
* where the {@link Formatters#SIMPLE} is leveraged.
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchiveFactory.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchiveFactory.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchiveFactory.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -17,7 +17,8 @@
package org.jboss.shrinkwrap.api;
/**
- *
+ * Responsible for creating {@link Archive}s, which may be
+ * presented to the caller in a designated {@link Assignable} view.
*
* @author <a href="mailto:andrew.rubinger at jboss.org">ALR</a>
* @version $Revision: $
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchivePath.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchivePath.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/ArchivePath.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -16,11 +16,9 @@
*/
package org.jboss.shrinkwrap.api;
-import org.jboss.shrinkwrap.api.asset.Asset;
-
/**
* Represents a target context within an {@link Archive} under
- * which an {@link Asset} may be found.
+ * which an {@link Node} may be found.
*
* @author <a href="mailto:andrew.rubinger at jboss.org">ALR</a>
* @version $Revision: $
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Assignable.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Assignable.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Assignable.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -18,7 +18,11 @@
/**
* General interface for representing entities such
- * as {@link Archive}s and descriptors as different extension types.
+ * as {@link Archive}s, importers and exporters as
+ * different extension types. The {@link Assignable} type is typically
+ * the end-user view. In effect all {@link Assignable}
+ * types achieve some limited form of multiple inheritance via
+ * a wrapping mechanism.
*
* @author <a href="mailto:aslak at conduct.no">Aslak Knutsen</a>
* @version $Revision: $
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filter.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filter.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filter.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -17,10 +17,9 @@
package org.jboss.shrinkwrap.api;
/**
- * Filter
- *
- * Used to filter what to add to the target {@link Archive}.
- * Used on 'multi' add operations like {@link Archive#merge(Archive, Filter)}.
+ * Used to filter inputs to be added to the target {@link Archive}.
+ * Used on multi-add operations such as
+ * {@link Archive#merge(Archive, Filter)}.
*
* @author <a href="mailto:aslak at conduct.no">Aslak Knutsen</a>
* @version $Revision: $
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filters.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filters.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Filters.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -16,8 +16,13 @@
*/
package org.jboss.shrinkwrap.api;
+import java.util.regex.Pattern;
+
+import javax.annotation.processing.Filer;
+
/**
- * Filters
+ * Factory class for the creation of new {@link Filter}
+ * instances
*
* @author <a href="mailto:aslak at conduct.no">Aslak Knutsen</a>
* @version $Revision: $
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/IllegalArchivePathException.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/IllegalArchivePathException.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/IllegalArchivePathException.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -19,8 +19,6 @@
import org.jboss.shrinkwrap.api.asset.Asset;
/**
- * IllegalPathException
- *
* Exception thrown when trying to add a {@link Node} on and invalid path
* within the {@link Archive} (i.e. you are trying to add an asset to
* "/test.txt/somethingelse.txt" where test.txt is an {@link Asset})
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Node.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Node.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/Node.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -5,28 +5,32 @@
import org.jboss.shrinkwrap.api.asset.Asset;
/**
- * Represents an entry inside an {@link Archive}. It can be a directory or an {@link Asset}.
+ * Represents an entry inside an {@link Archive}.
+ * Indicates a directory if {@link Node#getAsset()}
+ * returns null. May be the parent of child
+ * {@link Node}s. Lives inside the {@link Archive} under the context
+ * denoted by {@link Node#getPath()}.
*
* @author <a href="mailto:german.escobarc at gmail.com">German Escobar</a>
*/
public interface Node
{
-
+
/**
* @return The {@link Asset} this node holds, null if it is a directory
*/
Asset getAsset();
-
+
/**
* @return The child nodes of this node or, an empty set if it has no
* children or holds an asset. This method will never return null.
* The returned Set will be an immutable view.
*/
Set<Node> getChildren();
-
+
/**
* @return The path where this node is placed within the {@link Archive}
*/
ArchivePath getPath();
-
+
}
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/SecurityActions.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/SecurityActions.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/SecurityActions.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -23,8 +23,6 @@
import java.security.PrivilegedExceptionAction;
/**
- * SecurityActions
- *
* A set of privileged actions that are not to leak out
* of this package
*
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/Asset.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/Asset.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/Asset.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -20,11 +20,13 @@
import org.jboss.shrinkwrap.api.Archive;
import org.jboss.shrinkwrap.api.ArchivePath;
+import org.jboss.shrinkwrap.api.Node;
/**
- * Represents content
- * stored under some context (a {@link ArchivePath})
- * within an {@link Archive}
+ * Represents byte-based content.
+ * Typically stored within a {@link Node} inside of an {@link Archive}
+ * under a context {@link ArchivePath}. May be added
+ * directly to all {@link Archive} types.
*
* @author <a href="mailto:aslak at conduct.no">Aslak Knutsen</a>
* @author <a href="mailto:andrew.rubinger at jboss.org">ALR</a>
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayAsset.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayAsset.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayAsset.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -114,6 +114,6 @@
@Override
public String toString()
{
- return "ByteArrayAsset [content size=" + content.length + "bytes]";
+ return ByteArrayAsset.class.getSimpleName() + " [content size=" + content.length + "bytes]";
}
}
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayIOUtil.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayIOUtil.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/ByteArrayIOUtil.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -23,8 +23,6 @@
import java.util.logging.Logger;
/**
- * ByteArrayIOUtil
- *
* Package private class that helps get byte array from {@link InputStream}.
* Needed by the common assets in api.
*
@@ -44,7 +42,7 @@
* @throws IllegalArgumentException If the stream was not specified
* @return the byte[] for the given InputStream
*/
- public static byte[] asByteArray(final InputStream in) throws IllegalArgumentException
+ static byte[] asByteArray(final InputStream in) throws IllegalArgumentException
{
// Precondition check
if (in == null) {
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/EmptyAsset.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/EmptyAsset.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/EmptyAsset.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -13,6 +13,11 @@
public enum EmptyAsset implements Asset {
INSTANCE;
+ /**
+ * Empty contents
+ */
+ final byte[] content = new byte[0];
+
//-------------------------------------------------------------------------------------||
// Required Implementations -----------------------------------------------------------||
//-------------------------------------------------------------------------------------||
@@ -23,7 +28,7 @@
@Override
public InputStream openStream()
{
- return new ByteArrayInputStream(new byte[0]);
+ return new ByteArrayInputStream(content);
}
/**
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/FileAsset.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/FileAsset.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/FileAsset.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -73,4 +73,14 @@
throw new RuntimeException("Could not open file " + file, e);
}
}
+
+ /**
+ * {@inheritDoc}
+ * @see java.lang.Object#toString()
+ */
+ @Override
+ public String toString()
+ {
+ return FileAsset.class.getSimpleName() + " [file=" + file.getAbsolutePath() + "]";
+ }
}
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/SecurityActions.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/SecurityActions.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/SecurityActions.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -21,8 +21,6 @@
import java.security.PrivilegedAction;
/**
- * SecurityActions
- *
* A set of privileged actions that are not to leak out
* of this package
*
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/StringAsset.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/StringAsset.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/StringAsset.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -5,7 +5,6 @@
import java.util.logging.Level;
import java.util.logging.Logger;
-
/**
* Implementation of an {@link Asset} backed by a String
*
@@ -78,7 +77,7 @@
@Override
public String toString()
{
- return "StringAsset [content size=" + content.length() + " bytes]";
+ return StringAsset.class.getSimpleName() + " [content size=" + content.length() + " bytes]";
}
}
Modified: shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/UrlAsset.java
===================================================================
--- shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/UrlAsset.java 2010-05-25 17:41:33 UTC (rev 4441)
+++ shrinkwrap/trunk/api/src/main/java/org/jboss/shrinkwrap/api/asset/UrlAsset.java 2010-05-25 18:23:20 UTC (rev 4442)
@@ -20,7 +20,6 @@
import java.io.InputStream;
import java.net.URL;
-
/**
* Implementation of an {@link Asset} backed by a {@link URL}.
* The URL may be of any backing protocol supported by the runtime
@@ -66,4 +65,14 @@
throw new RuntimeException("Could not open stream for url " + url.toExternalForm(), e);
}
}
+
+ /**
+ * {@inheritDoc}
+ * @see java.lang.Object#toString()
+ */
+ @Override
+ public String toString()
+ {
+ return UrlAsset.class.getSimpleName() + " [url=" + url.toExternalForm() + "]";
+ }
}
More information about the jboss-svn-commits
mailing list