Return-Path: X-Original-To: apmail-commons-commits-archive@minotaur.apache.org Delivered-To: apmail-commons-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 5386D102FE for ; Mon, 14 Oct 2013 16:29:16 +0000 (UTC) Received: (qmail 53205 invoked by uid 500); 14 Oct 2013 16:29:15 -0000 Delivered-To: apmail-commons-commits-archive@commons.apache.org Received: (qmail 53140 invoked by uid 500); 14 Oct 2013 16:29:15 -0000 Mailing-List: contact commits-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 53131 invoked by uid 99); 14 Oct 2013 16:29:15 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 14 Oct 2013 16:29:15 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 14 Oct 2013 16:29:12 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 028C7238883D; Mon, 14 Oct 2013 16:28:51 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@commons.apache.org From: mbenson@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20131014162851.028C7238883D@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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}, + *

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:

+ *

+ * You might see such a typesafe API as: + * 

+ * class Typesafe {
+ *   <T> T obtain(Class<T> type, ...);
+ * }
+ *
+ * Consumed in the manner of: + * 
+ * Foo foo = typesafe.obtain(Foo.class, ...);
+ *
+ * Yet, you run into problems when you want to do this with a parameterized type: + * 
+ * List<String> listOfString = typesafe.obtain(List.class, ...); // could only give us a raw List
+ *
+ * {@code java.lang.reflect.Type} might provide some value: + * 
+ * Type listOfStringType = ...; // firstly, how to obtain this? Doable, but not straightforward.
+ * List<String> listOfString = (List<String>) typesafe.obtain(listOfStringType, ...); // nongeneric Type would necessitate a cast
+ *
+ * The "type literal" concept was introduced to provide an alternative, i.e.: + * 
+ * class Typesafe {
+ *   <T> T obtain(TypeLiteral<T> type, ...);
+ * }
+ *
+ * Consuming code looks like: + * 
+ * List<String> listOfString = typesafe.obtain(new TypeLiteral<List<String>>() {}, ...);
+ *
+ * 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. + *

+ *

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: + * 

+ *   <T> T obtain(Typed<T> typed, ...);
+ *
+ *

*/ public abstract class TypeLiteral implements Typed { 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 {