You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2018/01/06 20:51:28 UTC
juneau git commit: Javadoc updates.
Repository: juneau
Updated Branches:
refs/heads/master 5d827126e -> 972d4695e
Javadoc updates.
Project: http://git-wip-us.apache.org/repos/asf/juneau/repo
Commit: http://git-wip-us.apache.org/repos/asf/juneau/commit/972d4695
Tree: http://git-wip-us.apache.org/repos/asf/juneau/tree/972d4695
Diff: http://git-wip-us.apache.org/repos/asf/juneau/diff/972d4695
Branch: refs/heads/master
Commit: 972d4695eec068b8eb0eded6dba31d9e525390ce
Parents: 5d82712
Author: JamesBognar <ja...@apache.org>
Authored: Sat Jan 6 15:51:22 2018 -0500
Committer: JamesBognar <ja...@apache.org>
Committed: Sat Jan 6 15:51:22 2018 -0500
----------------------------------------------------------------------
.../java/org/apache/juneau/PropertyStore.java | 152 ++++++++++++++-----
1 file changed, 111 insertions(+), 41 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/juneau/blob/972d4695/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/PropertyStore.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/PropertyStore.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/PropertyStore.java
index 706a21c..ef7c8bf 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/PropertyStore.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/PropertyStore.java
@@ -20,7 +20,6 @@ import java.util.*;
import org.apache.juneau.PropertyStoreBuilder.*;
import org.apache.juneau.internal.*;
import org.apache.juneau.json.*;
-import org.apache.juneau.serializer.*;
/**
@@ -30,6 +29,8 @@ import org.apache.juneau.serializer.*;
* The general idea behind a property store is to serve as a reusable configuration of an artifact (e.g. a Serializer)
* such that the artifact can be cached and reused if the property stores are 'equal'.
*
+ * <h6 class='topic'>Concept</h6>
+ *
* <p>
* For example, two serializers of the same type created with the same configuration will always end up being
* the same serializer:
@@ -44,85 +45,154 @@ import org.apache.juneau.serializer.*;
* This has the effect of significantly improving performance, especially if you're creating many Serializers and
* Parsers.
*
+ * <h6 class='topic'>PropertyStoreBuilder</h6>
+ *
+ * <p>
+ * The {@link PropertyStoreBuilder} class is used to build up and instantiate immutable <code>PropertyStore</code>
+ * objects.
+ *
+ * <p>
+ * In the example above, the property store being built looks like the following:
+ *
+ * <p class='bcode'>
+ * PropertyStore ps = PropertyStore
+ * .<jsm>create</jsm>()
+ * .set(<js>"BeanContext.pojoSwaps.lc"</js>, MySwap.<jk>class</jk>)
+ * .set(<js>"JsonSerializer.simpleMode.b"</js>, <jk>true</jk>)
+ * .build();
+ * </p>
+ *
+ * <p>
+ * Property stores are immutable, comparable, and their hashcodes are calculated exactly one time.
+ * That makes them particularly suited for use as hashmap keys, and thus for caching reusable serializers and parsers.
+ *
+ * <h6 class='topic'>Property naming convention</h6>
+ *
* <p>
* Property names must have the following format...
* <p class='bcode'>
- * <js>"{group}.{name}.{type}"</js>
+ * <js>"{class}.{name}.{type}"</js>
* </p>
+ * <p>
* ...where the parts consist of the following...
* <ul>
- * <li><js>"{group}"</js> - The group name of the property (e.g. <js>"JsonSerializer"</js>).
+ * <li><js>"{class}"</js> - The group name of the property (e.g. <js>"JsonSerializer"</js>).
* <br>It's always going to be the simple class name of the class it's associated with.
* <li><js>"{name}"</js> - The property name (e.g. <js>"useWhitespace"</js>).
* <li><js>"{type}"</js> - The property data type.
* <br>A 1 or 2 character string that identifies the data type of the property.
* <br>Valid values are:
* <ul>
- * <li><js>"s"<js>: <code>String</code>
- * <li><js>"b"<js>: <code>Boolean</code>
- * <li><js>"i"<js>: <code>Integer</code>
- * <li><js>"c"<js>: <code>Class</code>
- * <li><js>"o"<js>: <code>Object</code>
- * <li><js>"ss"<js>: <code>TreeSet<String></code>
- * <li><js>"si"<js>: <code>TreeSet<Integer></code>
- * <li><js>"sc"<js>: <code>TreeSet<Class></code>
- * <li><js>"ls"<js>: <code>ArrayList<String></code>
- * <li><js>"li"<js>: <code>ArrayList<Integer></code>
- * <li><js>"lc"<js>: <code>ArrayList<Class></code>
- * <li><js>"lo"<js>: <code>ArrayList<Object></code>
- * <li><js>"ms"<js>: <code>TreeMap<String,String></code>
- * <li><js>"mi"<js>: <code>TreeMap<String,Integer></code>
- * <li><js>"mc"<js>: <code>TreeMap<String,Class></code>
- * <li><js>"mo"<js>: <code>TreeMap<String,Object></code>
+ * <li><js>"s"</js>: <code>String</code>
+ * <li><js>"b"</js>: <code>Boolean</code>
+ * <li><js>"i"</js>: <code>Integer</code>
+ * <li><js>"c"</js>: <code>Class</code>
+ * <li><js>"o"</js>: <code>Object</code>
+ * <li><js>"ss"</js>: <code>TreeSet<String></code>
+ * <li><js>"si"</js>: <code>TreeSet<Integer></code>
+ * <li><js>"sc"</js>: <code>TreeSet<Class></code>
+ * <li><js>"ls"</js>: <code>Linkedlist<String></code>
+ * <li><js>"li"</js>: <code>Linkedlist<Integer></code>
+ * <li><js>"lc"</js>: <code>Linkedlist<Class></code>
+ * <li><js>"lo"</js>: <code>Linkedlist<Object></code>
+ * <li><js>"sms"</js>: <code>TreeMap<String,String></code>
+ * <li><js>"smi"</js>: <code>TreeMap<String,Integer></code>
+ * <li><js>"smc"</js>: <code>TreeMap<String,Class></code>
+ * <li><js>"smo"</js>: <code>TreeMap<String,Object></code>
+ * <li><js>"oms"</js>: <code>LinkedHashMap<String,String></code>
+ * <li><js>"omi"</js>: <code>LinkedHashMap<String,Integer></code>
+ * <li><js>"omc"</js>: <code>LinkedHashMap<String,Class></code>
+ * <li><js>"omo"</js>: <code>LinkedHashMap<String,Object></code>
* </ul>
* </ul>
*
* <p>
- * For example, the {@link JsonSerializer} extends from {@link Serializer} and {@link BeanContext}, and therefore
- * is configured by properties defined in the <js>"JsonSerializer"</js>, <js>"Serializer"</js>, and <js>"BeanContext"</js>
- * groups. Since serializers and bean contexts can be relatively expensive to instantiate, we can cache and
- * reuse <code>JsonSerializer</code> instances if the property store used to instantiate them have equivalent
- * <js>"JsonSerializer"</js>, <js>"Serializer"</js>, and <js>"BeanContext"</js> groups.
+ * For example, <js>"BeanContext.pojoSwaps.lc"</js> refers to a property on the <code>BeanContext</code> class
+ * called <code>pojoSwaps</code> that has a data type of <code>List<Class></code>.
+ *
+ * <h6 class='topic'>Property value normalization</h6>
*
* <p>
- * Set and list properties have the additional convenience 'command' names for adding and removing entries:
- * <p class='bcode'>
- * <js>"{group}.{name}.{type}/add"</js> <jc>// Add a value to the set/list.</jc>
- * <js>"{group}.{name}.{type}/remove"</js> <jc>// Remove a value from the set/list.</jc>
- * </p>
+ * Property values get 'normalized' when they get set.
+ * For example, calling <code>propertyStore.set(<js>"BeanContext.debug.b"</js>, <js>"true"</js>)</code> will cause the property
+ * value to be converted to a boolean.
+ *
+ * <h6 class='topic'>Set types</h6>
*
* <p>
- * Set properties are typically used in cases where the order of the value is not important.
- * A <code>TreeSet</code> is used so that the order in which you add elements does not affect the resulting order
- * of the property.
+ * The <js>"sX"</js> property types are sorted sets.
+ * <br>Use these for collections of objects where the order is not important.
+ * <br>Internally, a <code>TreeSet</code> is used so that the order in which you add elements does not affect the
+ * resulting order of the property.
+ *
+ * <h6 class='topic'>List types</h6>
+ *
+ * <p>
+ * The <js>"lX"</js> property types are ordered lists.
+ * <br>Use these in cases where the order in which entries are added is important.
*
* <p>
- * List properties are typically used in cases where the order in which entries are added is important.
* Adding to a list property will cause the new entries to be added to the BEGINNING of the list.
- * This ensures that the resulting order of the list is in most-to-least importance.
+ * <br>This ensures that the resulting order of the list is in most-to-least importance.
+ *
+ * <p>
* For example, multiple calls to <code>pojoSwaps()</code> causes new entries to be added to the beginning of the list
* so that previous values can be 'overridden':
* <p class='bcode'>
- * <jc>// Swap order: [MySwap2.class, MySwap1.class]</jc>
- * JsonSerializer.create().pojoSwaps(MySwap1.class).pojoSwaps(MySwap2.class).build();
+ * <jc>// Swap order: [MySwap2.class, MySwap1.class]</jc>
+ * JsonSerializer.create().pojoSwaps(MySwap1.<jk>class</jk>).pojoSwaps(MySwap2.<jk>class</jk>).build();
* </p>
+ *
* <p>
* Note that the order is different when passing multiple values into the <code>pojoSwaps()</code> method, in which
* case the order should be first-match-wins:
* <p class='bcode'>
- * <jc>// Swap order: [MySwap1.class, MySwap2.class]</jc>
- * JsonSerializer.create().pojoSwaps(MySwap1.class,MySwap2.class).build();
+ * <jc>// Swap order: [MySwap1.class, MySwap2.class]</jc>
+ * JsonSerializer.create().pojoSwaps(MySwap1.<jk>class</jk>,MySwap2.<jk>class</jk>).build();
+ * </p>
+ *
+ * <p>
+ * Combined, the results look like this:
+ * <p class='bcode'>
+ * <jc>// Swap order: [MySwap4.class, MySwap3.class, MySwap1.class, MySwap2.class]</jc>
+ * JsonSerializer
+ * .create()
+ * .pojoSwaps(MySwap1.<jk>class</jk>,MySwap2.<jk>class</jk>)
+ * .pojoSwaps(MySwap3.<jk>class</jk>)
+ * .pojoSwaps(MySwap4.<jk>class</jk>)
+ * .build();
+ * </p>
+ *
+ * <h6 class='topic'>Map types</h6>
+ *
+ * <p>
+ * The <js>"smX"</js> and <js>"omX"</js> are sorted and order maps respectively.
+ *
+ * <h6 class='topic'>Command properties</h6>
+ *
+ * <p>
+ * Set and list properties have the additional convenience 'command' names for adding and removing entries:
+ * <p class='bcode'>
+ * <js>"{class}.{name}.{type}/add"</js> <jc>// Add a value to the set/list.</jc>
+ * <js>"{class}.{name}.{type}/remove"</js> <jc>// Remove a value from the set/list.</jc>
* </p>
*
* <p>
* Map properties have the additional convenience property name for adding and removing map entries:
* <p class='bcode'>
- * <js>"{group}.{name}.{type}/add.{key}"</js> <jc>// Add a map entry (or delete if the value is null).</jc>
+ * <js>"{class}.{name}.{type}/add.{key}"</js> <jc>// Add a map entry (or delete if the value is null).</jc>
* </p>
*
+ * <h6 class='topic'>Setting properties</h6>
+ *
* <p>
- * Property stores are entirely immutable which means their hashcode is calculated exactly once, meaning they
- * are particularly good for use as hashmap keys.
+ * TODO
+ *
+ * <h6 class='topic'>Retrieving properties</h6>
+ *
+ * <p>
+ * TODO
+ *
*/
@SuppressWarnings("unchecked")
public final class PropertyStore {