v1.7.2: writer reader EasyML APIs and HexFormat

Author: cordisvictor

README.md

@@ -60,6 +60,11 @@ for a higher control compared to the EasyML Facade.
 
 ### Release Notes
 
+Release 1.7.2
+- refactor: improved XML writer, reader and EasyML APIs
+- feature: added HexFormat strategy.
+
+
 Release 1.7.1
 - feature: added List.of, Map.of, Set.of strategies.
 - feature: added java.util.Collections unmodifiableList, unmodifiableMap, unmodifiableSet strategies.

easyml/src/net/sourceforge/easyml/EasyML.java

@@ -84,7 +84,7 @@
  * objects.<br/>
  *
  * @author Victor Cordis ( cordis.victor at gmail.com)
- * @version 1.7.1
+ * @version 1.7.2
  * @see XMLReader
  * @see XMLWriter
  * @since 1.0
@@ -183,7 +183,7 @@ public void applyTo(XMLWriter writer) {
      */
     public EasyML() {
         this.writerPrototype = new XMLWriter();
-        this.readerPrototype = new XMLReader(new ConcurrentHashMap<>());
+        this.readerPrototype = new XMLReader(ConcurrentHashMap::new);
         defaultConfiguration(this.writerPrototype);
         defaultConfiguration(this.readerPrototype);
         this.perThreadWriter = ThreadLocal.withInitial(() -> new XMLWriter(writerPrototype));
@@ -258,6 +258,7 @@ public static void defaultConfiguration(XMLWriter writer) {
         composite.add(HashMapStrategy.INSTANCE);
         composite.add(HashSetStrategy.INSTANCE);
         composite.add(HashtableStrategy.INSTANCE);
+        composite.add(HexFormatStrategy.INSTANCE);
         composite.add(IdentityHashMapStrategy.INSTANCE);
         ImmutableCollectionsStrategies.forEach(composite::add);
         composite.add(LinkedHashMapStrategy.INSTANCE);
@@ -354,6 +355,7 @@ public static void defaultConfiguration(XMLReader reader) {
         composite.put(HashMapStrategy.NAME, HashMapStrategy.INSTANCE);
         composite.put(HashSetStrategy.NAME, HashSetStrategy.INSTANCE);
         composite.put(HashtableStrategy.NAME, HashtableStrategy.INSTANCE);
+        composite.put(HexFormatStrategy.NAME, HexFormatStrategy.INSTANCE);
         composite.put(IdentityHashMapStrategy.NAME, IdentityHashMapStrategy.INSTANCE);
         ImmutableCollectionsStrategies.forEach(s -> composite.put(s.name(), s));
         composite.put(LinkedHashMapStrategy.NAME, LinkedHashMapStrategy.INSTANCE);
@@ -382,6 +384,9 @@ public static void defaultConfiguration(XMLReader reader) {
         composite.put(PatternStrategy.NAME, PatternStrategy.INSTANCE);
     }
 
+    /**
+     * To be used by {@linkplain EasyMLBuilder} only.
+     */
     EasyML(Style style, Supplier<XmlPullParser> xmlPullParserProvider,
            String dateFormat, String customRootTag, Map<Class, String> classToAlias, Map<Field, String> fieldToAlias,
            Set<Field> excludedFields, XMLReader.SecurityPolicy deserializationSecurityPolicy,
@@ -574,7 +579,7 @@ public XMLWriter newWriter(Document out) {
      */
     public XMLReader newReader(Reader in) {
         final XMLReader ret = new XMLReader(readerPrototype);
-        ret.reset(in, maybeProvidedXmlPullParser());
+        ret.reset(in, maybeXmlPullParserProvider());
         return ret;
     }
 
@@ -590,7 +595,9 @@ public XMLReader newReader(Reader in) {
      * @return a new shared-configuration reader
      */
     public XMLReader newReader(InputStream in) {
-        return this.newReader(new InputStreamReader(in));
+        final XMLReader ret = new XMLReader(readerPrototype);
+        ret.reset(in, maybeXmlPullParserProvider());
+        return ret;
     }
 
     /**
@@ -625,8 +632,11 @@ public XMLReader newReader(Document in) {
     public void serialize(Object o, Writer out) {
         final XMLWriter writer = this.perThreadWriter.get();
         writer.reset(out);
-        writer.write(o);
-        writer.flush();
+        try {
+            writer.write(o);
+        } finally {
+            writer.flush();
+        }
     }
 
     /**
@@ -668,8 +678,11 @@ public String serialize(Object o) {
     public void serialize(Object o, Document out) {
         final XMLWriter writer = this.perThreadWriter.get();
         writer.reset(out);
-        writer.write(o);
-        writer.flush();
+        try {
+            writer.write(o);
+        } finally {
+            writer.flush();
+        }
     }
 
     /**
@@ -682,11 +695,11 @@ public void serialize(Object o, Document out) {
      */
     public Object deserialize(Reader in) {
         final XMLReader reader = this.perThreadReader.get();
-        reader.reset(in, maybeProvidedXmlPullParser());
+        reader.reset(in, maybeXmlPullParserProvider());
         return reader.read();
     }
 
-    private XmlPullParser maybeProvidedXmlPullParser() {
+    private XmlPullParser maybeXmlPullParserProvider() {
         return this.xmlPullParserProvider != null ? this.xmlPullParserProvider.get() : null;
     }
 
@@ -733,7 +746,7 @@ public Object deserialize(Document in) {
     /**
      * Releases the XML writer, if any, belonging to the current thread. If this
      * method isn't invoked, the XML writer will be released anyway at the
-     * current threads death.
+     * current thread's death.
      * <br>
      * <b>Note:</b> this is an advanced feature and should be used only if the
      * caller knows this thread won't be using this EasyML instance for
@@ -746,7 +759,7 @@ public void releaseCurrentWriter() {
     /**
      * Releases the XML reader, if any, belonging to the current thread. If this
      * method isn't invoked, the XML reader will be released anyway at the
-     * current threads death.
+     * current thread's death.
      * <br>
      * <b>Note:</b> this is an advanced feature and should be used only if the
      * caller knows this thread won't be using this EasyML instance for

easyml/src/net/sourceforge/easyml/XMLReader.java

@@ -65,7 +65,7 @@
  * shared configuration can be created, via constructors.
  *
  * @author Victor Cordis ( cordis.victor at gmail.com)
- * @version 1.6.0
+ * @version 1.7.2
  * @see XMLWriter
  * @since 1.0
  */
@@ -353,8 +353,8 @@ public final Object read() {
         /**
          * Reads from the current position, recursively.
          *
-         * @param componentType array componentType, if the expected result is
-         *                      an array with no class attribute, null otherwise
+         * @param componentType array componentType, if the expected result is an array with no class attribute,
+         *                      null otherwise
          * @return the read object
          */
         @Override
@@ -391,6 +391,14 @@ public S put(String key, S value) {
         }
     }
 
+    @FunctionalInterface
+    interface AliasingReflectionCacheSupplier {
+
+        AliasingReflectionCacheSupplier DEFAULT = HashMap::new;
+
+        Map<String, Object> get();
+    }
+
     private static final char FIELD_FQN_SEPARATOR = '#';
     private Driver driver;
     private boolean beforeRoot;
@@ -405,21 +413,47 @@ public S put(String key, S value) {
     /* default*/ SecurityPolicy securityPolicy;
 
     /**
-     * Creates a new configuration prototype instance, to be used by
-     * {@linkplain EasyML} only.
+     * Creates a new configuration prototype instance.
+     * To be used by {@linkplain EasyML} only.
      */
-    XMLReader(Map<String, Object> aliasFieldCache) {
+    XMLReader(AliasingReflectionCacheSupplier getAliasingReflectionCache) {
         this.driver = null;
-        this.init(aliasFieldCache);
+        this.init(getAliasingReflectionCache);
+    }
+
+    private void init(AliasingReflectionCacheSupplier getAliasingReflectionCache) {
+        this.beforeRoot = true;
+        this.rootTag = DTD.ELEMENT_EASYML;
+        this.decoded = new HashMap<>();
+        this.sharedConfiguration = false;
+        this.context = new UnmarshalContextImpl();
+        this.cachedAliasingReflection = getAliasingReflectionCache.get();
+        this.simpleStrategies = new StrategyHashMap<>();
+        this.compositeStrategies = new StrategyHashMap<>();
+        this.dateFormat = new SimpleDateFormat(DTD.FORMAT_DATE);
+        this.securityPolicy = null; // lazy.
+        // add DTD strategies by default:
+        this.simpleStrategies.put(DTD.TYPE_BASE64, Base64Strategy.INSTANCE);
+        this.simpleStrategies.put(DTD.TYPE_BOOLEAN, BooleanStrategy.INSTANCE);
+        this.simpleStrategies.put(DTD.TYPE_DATE, DateStrategy.INSTANCE);
+        this.simpleStrategies.put(DTD.TYPE_DOUBLE, DoubleStrategy.INSTANCE);
+        this.simpleStrategies.put(DTD.TYPE_INT, IntStrategy.INSTANCE);
+        this.simpleStrategies.put(DTD.TYPE_STRING, StringStrategy.INSTANCE);
+        // add NON-DTD strategies for primitives, since we need to support the primitive API:
+        this.simpleStrategies.put(ByteStrategy.NAME, ByteStrategy.INSTANCE);
+        this.simpleStrategies.put(CharacterStrategy.NAME, CharacterStrategy.INSTANCE);
+        this.simpleStrategies.put(FloatStrategy.NAME, FloatStrategy.INSTANCE);
+        this.simpleStrategies.put(LongStrategy.NAME, LongStrategy.INSTANCE);
+        this.simpleStrategies.put(ShortStrategy.NAME, ShortStrategy.INSTANCE);
     }
 
     /**
-     * Creates a new shared-configuration instance, to be used by
-     * {@linkplain EasyML} only.
+     * Creates a new shared-configuration instance.
+     * To be used by {@linkplain EasyML} only.
      */
-    XMLReader(XMLReader configured) {
+    XMLReader(XMLReader prototype) {
         this.driver = null;
-        this.initIdentically(configured);
+        this.initIdentically(prototype);
     }
 
     private void initIdentically(XMLReader other) {
@@ -444,37 +478,7 @@ private void initIdentically(XMLReader other) {
      */
     public XMLReader(Reader reader) {
         this.driver = new XMLReaderTextDriver(this, reader);
-        this.init();
-    }
-
-    private void init() {
-        this.init(new HashMap<>());
-    }
-
-    private void init(Map<String, Object> aliasReflectCache) {
-        this.beforeRoot = true;
-        this.rootTag = DTD.ELEMENT_EASYML;
-        this.decoded = new HashMap<>();
-        this.sharedConfiguration = false;
-        this.context = new UnmarshalContextImpl();
-        this.cachedAliasingReflection = aliasReflectCache;
-        this.simpleStrategies = new StrategyHashMap<>();
-        this.compositeStrategies = new StrategyHashMap<>();
-        this.dateFormat = new SimpleDateFormat(DTD.FORMAT_DATE);
-        this.securityPolicy = null; // lazy.
-        // add DTD strategies by default:
-        this.simpleStrategies.put(DTD.TYPE_BASE64, Base64Strategy.INSTANCE);
-        this.simpleStrategies.put(DTD.TYPE_BOOLEAN, BooleanStrategy.INSTANCE);
-        this.simpleStrategies.put(DTD.TYPE_DATE, DateStrategy.INSTANCE);
-        this.simpleStrategies.put(DTD.TYPE_DOUBLE, DoubleStrategy.INSTANCE);
-        this.simpleStrategies.put(DTD.TYPE_INT, IntStrategy.INSTANCE);
-        this.simpleStrategies.put(DTD.TYPE_STRING, StringStrategy.INSTANCE);
-        // add NON-DTD strategies for primitives, since we need to support the primitive API:
-        this.simpleStrategies.put(ByteStrategy.NAME, ByteStrategy.INSTANCE);
-        this.simpleStrategies.put(CharacterStrategy.NAME, CharacterStrategy.INSTANCE);
-        this.simpleStrategies.put(FloatStrategy.NAME, FloatStrategy.INSTANCE);
-        this.simpleStrategies.put(LongStrategy.NAME, LongStrategy.INSTANCE);
-        this.simpleStrategies.put(ShortStrategy.NAME, ShortStrategy.INSTANCE);
+        this.init(AliasingReflectionCacheSupplier.DEFAULT);
     }
 
     /**
@@ -485,8 +489,7 @@ private void init(Map<String, Object> aliasReflectCache) {
      * @param in stream from which to read
      */
     public XMLReader(InputStream in) {
-        this.driver = new XMLReaderTextDriver(this, new InputStreamReader(in));
-        this.init();
+        this(new InputStreamReader(in));
     }
 
     /**
@@ -499,7 +502,7 @@ public XMLReader(InputStream in) {
      */
     public XMLReader(Reader reader, XmlPullParser parser) {
         this.driver = new XMLReaderTextDriver(this, reader, parser);
-        this.init();
+        this.init(AliasingReflectionCacheSupplier.DEFAULT);
     }
 
     /**
@@ -511,8 +514,7 @@ public XMLReader(Reader reader, XmlPullParser parser) {
      * @param parser to process the in XML with
      */
     public XMLReader(InputStream in, XmlPullParser parser) {
-        this.driver = new XMLReaderTextDriver(this, new InputStreamReader(in), parser);
-        this.init();
+        this(new InputStreamReader(in), parser);
     }
 
     /**
@@ -523,7 +525,21 @@ public XMLReader(InputStream in, XmlPullParser parser) {
      */
     public XMLReader(Document in) {
         this.driver = new XMLReaderDOMDriver(this, in);
-        this.init();
+        this.init(AliasingReflectionCacheSupplier.DEFAULT);
+    }
+
+    /**
+     * Creates a new instance with the given <code>driver</code>.
+     * For generic formats, other than XML.
+     *
+     * @param driver for generic formats
+     */
+    public XMLReader(XMLReader.Driver driver) {
+        if (driver == null) {
+            throw new IllegalArgumentException("driver: null");
+        }
+        this.driver = driver;
+        this.init(AliasingReflectionCacheSupplier.DEFAULT);
     }
 
     /**
@@ -1045,20 +1061,17 @@ private boolean isRootEnd() {
      * @param parser to use, null if default
      */
     public void reset(Reader reader, XmlPullParser parser) {
-        if (isReusableXMLReaderTextDriver()) {
+        if (this.driver != null && this.driver.getClass() == XMLReaderTextDriver.class) {
             ((XMLReaderTextDriver) this.driver).reset(reader, parser);
         } else {
-            this.driver = parser != null ? new XMLReaderTextDriver(this, reader, parser)
-                    : new XMLReaderTextDriver(this, reader);
+            this.driver = parser != null ?
+                    new XMLReaderTextDriver(this, reader, parser) :
+                    new XMLReaderTextDriver(this, reader);
         }
         this.decoded.clear();
         this.beforeRoot = true;
     }
 
-    private boolean isReusableXMLReaderTextDriver() {
-        return this.driver != null && this.driver.getClass() == XMLReaderTextDriver.class;
-    }
-
     /**
      * Resets this instance, setting it to the new <code>in</code> stream.
      *

easyml/src/net/sourceforge/easyml/XMLReaderTextDriver.java

@@ -194,8 +194,7 @@ protected void consumeFully() {
      * recreate and should be reused.
      *
      * @param in     the required input reader
-     * @param parser optional custom parser to replace the default pull-parse
-     *               implementation
+     * @param parser optional custom parser to replace the default pull-parse implementation
      */
     public void reset(Reader in, XmlPullParser parser) {
         if (parser != null) {