commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mben...@apache.org
Subject svn commit: r1531968 - in /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect: TypeLiteral.java Typed.java
Date Mon, 14 Oct 2013 16:28:50 GMT
Author: mbenson
Date: Mon Oct 14 16:28:50 2013
New Revision: 1531968

URL: http://svn.apache.org/r1531968
Log:
extended documentation for TypeLiteral/Typed

Modified:
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/TypeLiteral.java
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/Typed.java

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/TypeLiteral.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/TypeLiteral.java?rev=1531968&r1=1531967&r2=1531968&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/TypeLiteral.java
(original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/TypeLiteral.java
Mon Oct 14 16:28:50 2013
@@ -22,13 +22,51 @@ import java.lang.reflect.TypeVariable;
 import org.apache.commons.lang3.Validate;
 
 /**
- * Type literal comparable to {@code javax.enterprise.util.TypeLiteral},
+ * <p>Type literal comparable to {@code javax.enterprise.util.TypeLiteral},
  * made generally available outside the JEE context. Allows the passing around of
  * a "token" that represents a type in a typesafe manner, as opposed to
- * passing the (non-parameterized) {@link Type} object itself.
- * Additionally {@link TypeLiteral} implements the {@link Typed} interface which
- * is a generalization of this concept. It is suggested that APIs be defined in
- * terms of the interface, which others might implemented in custom classes.
+ * passing the (non-parameterized) {@link Type} object itself. Consider:</p>
+ * <p>
+ * You might see such a typesafe API as:
+ * <pre>
+ * class Typesafe {
+ *   &lt;T&gt; T obtain(Class&lt;T&gt; type, ...);
+ * }
+ * </pre>
+ * Consumed in the manner of:
+ * <pre>
+ * Foo foo = typesafe.obtain(Foo.class, ...);
+ * </pre>
+ * Yet, you run into problems when you want to do this with a parameterized type:
+ * <pre>
+ * List&lt;String&gt; listOfString = typesafe.obtain(List.class, ...); // could only
give us a raw List
+ * </pre>
+ * {@code java.lang.reflect.Type} might provide some value:
+ * <pre>
+ * Type listOfStringType = ...; // firstly, how to obtain this? Doable, but not straightforward.
+ * List&lt;String&gt; listOfString = (List&lt;String&gt;) typesafe.obtain(listOfStringType,
...); // nongeneric Type would necessitate a cast
+ * </pre>
+ * The "type literal" concept was introduced to provide an alternative, i.e.:
+ * <pre>
+ * class Typesafe {
+ *   &lt;T&gt; T obtain(TypeLiteral&lt;T&gt; type, ...);
+ * }
+ * </pre>
+ * Consuming code looks like:
+ * <pre>
+ * List&lt;String&gt; listOfString = typesafe.obtain(new TypeLiteral&lt;List&lt;String&gt;&gt;()
{}, ...);
+ * </pre>
+ * This has the effect of "jumping up" a level to tie a {@code java.lang.reflect.Type}
+ * to a type variable while simultaneously making it short work to obtain a
+ * {@code Type} instance for any given type, inline.
+ * </p>
+ * <p>Additionally {@link TypeLiteral} implements the {@link Typed} interface which
+ * is a generalization of this concept, and which may be implemented in custom classes.
+ * It is suggested that APIs be defined in terms of the interface, in the following manner:
+ * <pre>
+ *   &lt;T&gt; T obtain(Typed&lt;T&gt; typed, ...);
+ * </pre>
+ * </p>
  */
 public abstract class TypeLiteral<T> implements Typed<T> {
 

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/Typed.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/Typed.java?rev=1531968&r1=1531967&r2=1531968&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/Typed.java (original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/reflect/Typed.java Mon
Oct 14 16:28:50 2013
@@ -20,6 +20,7 @@ import java.lang.reflect.Type;
 
 /**
  * Generalization of "has a type."
+ * @see TypeLiteral
  */
 public interface Typed<T> {
 



Mime
View raw message