Merge branch 'feature-appendable-toString' into dev

Author: SimplyProgrammer

SerialX-core/src/main/java/org/ugp/serialx/converters/BooleanConverter.java

@@ -3,6 +3,8 @@
 import static java.lang.Boolean.*;
 import static org.ugp.serialx.Utils.equalsLowerCase;
 
+import java.io.IOException;
+
 /**
  * This converter is capable of converting {@link String}. 
  * Its case insensitive!
@@ -76,10 +78,14 @@ public Object parse(ParserRegistry myHomeRegistry, String str, Object... args)
 	}
 
 	@Override
-	public CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Object... args) 
+	public Appendable toString(Appendable source, ParserRegistry myHomeRegistry, Object obj, Object... args) throws IOException 
 	{
 		if (obj instanceof Boolean)
-			return isShorten() ? (boolean) obj ? "T" : "F" : (boolean) obj ? "true" : "false";
+		{
+			if (isShorten())
+				return source.append((boolean) obj ? 'T' : 'F');
+			return source.append((boolean) obj ? "true" : "false");
+		}
 		return CONTINUE;
 	}
 

SerialX-core/src/main/java/org/ugp/serialx/converters/CharacterConverter.java

@@ -1,5 +1,7 @@
 package org.ugp.serialx.converters;
 
+import java.io.IOException;
+
 /**
  * This converter is capable of converting {@link Character}.
  * Its case sensitive!
@@ -52,10 +54,10 @@ public Object parse(ParserRegistry myHomeRegistry, String str, Object... args)
 	}
 
 	@Override
-	public CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Object... args) 
+	public Appendable toString(Appendable source, ParserRegistry myHomeRegistry, Object obj, Object... args) throws IOException 
 	{
 		if (obj instanceof Character)
-			return "'"+(int) (char) obj+"'";
+			return source.append("'"+(int) (char) obj+"'");
 		return CONTINUE;
 	}
 

SerialX-core/src/main/java/org/ugp/serialx/converters/DataConverter.java

@@ -1,5 +1,7 @@
 package org.ugp.serialx.converters;
 
+import java.io.IOException;
+
 /**
  * This is DataParser with extended functionality! {@link DataConverter} can also parse data like DataParser but is also capable of converting them back to string!
  * This to string convertation is performed by {@link DataConverter#toString(Object)} and result of this convertation supposed to be parsable by {@link DataConverter#parse(String, Object...)} meaning one converter supposed to be parsing and converting via the same string format!
@@ -18,11 +20,37 @@ public interface DataConverter extends DataParser
 	 * @param args | Some additional args. This can be anything and it demands on implementation of DataConverter. Default SerialX API implementation will provide some flags about formating (2 ints)!
 	 * 
 	 * @return Object converted to string. Easiest way to do this is obj.toString() but you most likely want some more sofisticated formating.
-	 * Return {@link DataParser#CONTINUE} to tell that this converter is not suitable for converting this object! You most likely want to do this when obtained obj is not suitable instance!
+	 * <br>Return {@link DataParser#CONTINUE} to tell that this converter is not suitable for converting this object! You most likely want to do this when obtained obj is not suitable instance!
 	 * 
 	 * @since 1.3.0
 	 */
-	CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Object... args);
+	default CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Object... args)
+	{
+		try 
+		{
+			return (CharSequence) toString(new StringBuilder(), myHomeRegistry, obj, args);
+		} 
+		catch (IOException e) 
+		{
+			throw new RuntimeException(e); // Rare...
+		}
+	}
+	
+	/**
+	 * @param source | Source to append the properly stringified object (obj) into. Should be treated as only and only {@link Appendable}, no casting!
+	 * @param myHomeRegistry | Registry where this parser is registered provided by {@link ParserRegistry#parse(String, boolean, Class, Object...)} otherwise it demands on implementation (it should not be null)!
+	 * @param obj | Object to convert into string!
+	 * @param args | Some additional args. This can be anything and it demands on implementation of DataConverter. Default SerialX API implementation will provide some flags about formating (2 ints)!
+	 * 
+	 * @return The source appendable after stringified object (obj) was appropriately appended into it. Alternatively you can return null to signify error or that everything necessary was already appended and no further chars should be appended immediately after this obj's stringification.
+	 * <br>Return {@link DataParser#CONTINUE} to tell that this converter is not suitable for converting this object! You most likely want to do this when obtained obj is not suitable instance!
+	 * <br>Note: It is highly discouraged to append into this return!
+	 * 
+	 * @throws IOException When appending into source throws it... 
+	 * 
+	 * @since 1.3.9
+	 */
+	Appendable toString(Appendable source, ParserRegistry myHomeRegistry, Object obj, Object... args) throws IOException;
 
 	/**
 	 * @param myHomeRegistry | Registry of parsers (might be null)!

SerialX-core/src/main/java/org/ugp/serialx/converters/DataParser.java

@@ -1,5 +1,6 @@
 package org.ugp.serialx.converters;
 
+import java.io.IOException;
 import java.util.Collection;
 
 import org.ugp.serialx.LogProvider;
@@ -29,10 +30,11 @@ public interface DataParser
 
 	/**
 	 * This is connected with {@link DataParser#parse(String, Object...)} and {@link DataParser#parseObj(String, Object...)}! And its a way to tell that this parser is not suitable for parsing obtained string and search for optimal one should continue.
+	 * Should not be modified under any circumstances, always treat as immutable!
 	 * 
 	 * @since 1.3.0
 	 */
-	public static final String CONTINUE = new String();
+	public static final Appendable CONTINUE = new StringBuilder(0);
 
 	/**
 	 * This is DataParser registry. Here your parser implementations should be registered in order to work properly!
@@ -80,7 +82,7 @@ public static class ParserRegistry extends Registry<DataParser> implements DataP
 		private static final long serialVersionUID = -2598324826689380752L;
 
 		protected DataParser[] parsingCache;
-		protected DataParser[] convertingCache;
+		protected DataConverter[] convertingCache;
 
 		/**
 		 * Constructs an {@link ParserRegistry} with the specified initial capacity.
@@ -151,7 +153,7 @@ public DataParser getParserFor(String str, Object... args)
 		public DataConverter getConverterFor(Object obj, Object... args)
 		{
 			for (DataParser parser : this) 
-				if (parser instanceof DataConverter && ((DataConverter)parser).toString(this, obj, args) != CONTINUE)
+				if (parser instanceof DataConverter && ((DataConverter) parser).toString(this, obj, args) != CONTINUE)
 					return (DataConverter) parser;
 			return null;
 		}
@@ -167,25 +169,50 @@ public DataConverter getConverterFor(Object obj, Object... args)
 		 */
 		public CharSequence toString(Object obj, Object... args)
 		{
-			CharSequence str;
+			try 
+			{
+				return (CharSequence) toString(new StringBuilder(), obj, args);
+			} 
+			catch (IOException e) 
+			{
+				throw new RuntimeException(e);
+			}
+		}
+		
+		/**
+		 * @param source | Source to append the properly stringified object (obj) into. Should be treated as only and only {@link Appendable}, no casting!
+		 * @param obj | Object to convert into string!
+		 * @param args | Additional arguments that will be obtained in {@link DataParser#toString(String, Object...)}!
+		 * 
+		 * @return The source appendable after stringified object (obj) was appropriately appended into it. Alternatively you can return null to signify error or that everything necessary was already appended and no further chars should be appended immediately after this obj's stringification.
+		 * <br>Return {@link DataParser#CONTINUE} to tell that this converter is not suitable for converting this object! You most likely want to do this when obtained obj is not suitable instance!
+		 * <br>Note: It is highly discouraged to append into this return!
+		 * 
+		 * @throws IOException When appending into source throws it... 
+		 * 
+		 * @since 1.3.9
+		 */
+		public Appendable toString(Appendable source, Object obj, Object... args) throws IOException
+		{
+			Appendable str;
 			if (convertingCache != null)
-				for (DataParser parser : convertingCache)
-					if (parser != null && (str = ((DataConverter) parser).toString(this, obj, args)) != CONTINUE)
+				for (DataConverter parser : convertingCache)
+					if (parser != null && (str = parser.toString(source, this, obj, args)) != CONTINUE)
 						return str;
 
 			for (int i = 0, size = size(); i < size; i++) 
 			{
 				DataParser parser = get(i);
-				if (parser instanceof DataConverter && (str = ((DataConverter) parser).toString(this, obj, args)) != CONTINUE)
+				if (parser instanceof DataConverter && (str = ((DataConverter) parser).toString(source, this, obj, args)) != CONTINUE)
 				{
 					if (convertingCache != null && i < convertingCache.length)
-						convertingCache[i] = parser; 
+						convertingCache[i] = (DataConverter) parser;
 					return str;
 				}
 			}
 
 			LogProvider.instance.logErr("Unable to convert \"" + (obj == null ? "null" : obj.getClass().getName()) + "\" to string because none of registered converters were aplicable for this object!", null);
-			return null;
+			return source.append("null");
 		}
 
 		/**
@@ -299,9 +326,9 @@ public int[] preCache(Class<? extends DataParser> classOfParserToPrecache)
 				ret[0] = i;
 			}
 
-			if (i < convertingCache.length)
+			if (i < convertingCache.length && parser instanceof DataConverter)
 			{
-				convertingCache[i] = parser;
+				convertingCache[i] = (DataConverter) parser;
 				ret[1] = i;
 			}
 
@@ -319,7 +346,7 @@ public int[] preCache(Class<? extends DataParser> classOfParserToPrecache)
 		public void resetCache()
 		{
 			int size = size();
-			resetCache(new DataParser[size], new DataParser[size]);
+			resetCache(new DataParser[size], new DataConverter[size]);
 		}
 
 		/**
@@ -330,7 +357,7 @@ public void resetCache()
 		 * 
 		 * @since 1.3.5
 		 */
-		public void resetCache(DataParser[] parsingCache, DataParser[] convertingCache)
+		public void resetCache(DataParser[] parsingCache, DataConverter[] convertingCache)
 		{
 			if (parsingCache != null)
 				this.parsingCache = parsingCache;
@@ -363,7 +390,7 @@ public DataParser[] getParsingCache()
 		 * 
 		 * @since 1.3.5
 		 */
-		public DataParser[] getConverterCache()
+		public DataConverter[] getConverterCache()
 		{
 			return convertingCache;
 		}

SerialX-core/src/main/java/org/ugp/serialx/converters/NullConverter.java

@@ -2,6 +2,8 @@
 
 import static org.ugp.serialx.Utils.equalsLowerCase;
 
+import java.io.IOException;
+
 /**
  * This converter is capable of converting "nothing" otherwise known as null and {@link DataParser#VOID}.
  * Its case insensitive!
@@ -49,10 +51,10 @@ public Object parse(ParserRegistry registry, String str, Object... args)
 	}
 
 	@Override
-	public CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Object... args) 
+	public Appendable toString(Appendable source, ParserRegistry myHomeRegistry, Object obj, Object... args) throws IOException 
 	{
 		if (obj == null)
-			return "null";
+			return source.append("null");
 		return CONTINUE;
 	}
 

SerialX-core/src/main/java/org/ugp/serialx/converters/NumberConverter.java

@@ -2,6 +2,8 @@
 
 import static org.ugp.serialx.Utils.contains;
 
+import java.io.IOException;
+
 /**
  * This converter is capable of converting {@link Number} including all common implementations like {@link Double}, {@link Float}, {@link Integer} and others. They are determine by suffixes like in java!
  * Its case insensitive!
@@ -106,22 +108,23 @@ public Object parse(ParserRegistry myHomeRegistry, String arg, Object... args)
 	}
 
 	@Override
-	public CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Object... args) 
+	public Appendable toString(Appendable source, ParserRegistry myHomeRegistry, Object obj, Object... args) throws IOException 
 	{
 		if (obj instanceof Number)
 		{
-			StringBuilder str = new StringBuilder(format((Number) obj));
+			String str;
+			source.append(str = format((Number) obj));
 			if (obj instanceof Double && !contains(str, '.'))
-				str.append('D');
+				source.append('D');
 			else if (obj instanceof Float)
-				str.append('F');
+				source.append('F');
 			else if (obj instanceof Long)
-				str.append('L');
+				source.append('L');
 			else if (obj instanceof Short)
-				str.append('S');
+				source.append('S');
 			else if (obj instanceof Byte)
-				str.append('Y');
-			return str;
+				source.append('Y');
+			return source;
 		}
 		return CONTINUE;
 	}

SerialX-core/src/main/java/org/ugp/serialx/converters/ProtocolConverter.java

@@ -4,6 +4,7 @@
 import static org.ugp.serialx.Utils.indexOfNotInObj;
 import static org.ugp.serialx.Utils.splitValues;
 
+import java.io.IOException;
 import java.io.Serializable;
 import java.lang.reflect.InvocationTargetException;
 import java.util.ArrayList;
@@ -166,24 +167,24 @@ protected Object parse(ParserRegistry myHomeRegistry, Class<?> objClass, String
 	}
 
 	@Override
-	public CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Object... args)
+	public Appendable toString(Appendable source, ParserRegistry myHomeRegistry, Object obj, Object... args) throws IOException
 	{
-		return toString(myHomeRegistry, obj, null, args);
+		return toString(source, myHomeRegistry, obj, null, args);
 	}
 
 	/**
+	 * @param source | Source to append the properly stringified object (obj) into. Should be treated as only and only {@link Appendable}, no casting!
 	 * @param myHomeRegistry | Registry where this parser is registered provided by {@link ParserRegistry#parse(String, boolean, Class, Object...)} otherwise it demands on implementation (it should not be null)!
 	 * @param obj | Object to convert into string!
 	 * @param preferedProtocol | Protocol to use preferably.
 	 * @param args | Some additional args. This can be anything and it demands on implementation of DataConverter. Default SerialX API implementation will provide some flags about formating (2 ints)!
 	 * 
-	 * @return Object converted to string. Easiest way to do this is obj.toString() but you most likely want some more sofisticated formating.
-	 * Return {@link DataParser#CONTINUE} to tell that this converter is not suitable for converting this object! You most likely want to do this when obtained obj is not suitable instance!
+	 * @return In accordance with {@link DataConverter#toString(Appendable, org.ugp.serialx.converters.DataParser.ParserRegistry, Object, Object...)}.
 	 * 
 	 * @since 1.3.5
 	 */
 	@SuppressWarnings("unchecked")
-	public CharSequence toString(ParserRegistry myHomeRegistry, Object obj, SerializationProtocol<Object> preferedProtocol, Object... args) 
+	public Appendable toString(Appendable source, ParserRegistry myHomeRegistry, Object obj, SerializationProtocol<Object> preferedProtocol, Object... args) 
 	{
 		if (obj == null)
 			return CONTINUE;
@@ -205,42 +206,45 @@ public CharSequence toString(ParserRegistry myHomeRegistry, Object obj, Serializ
 			{
 				Object[] objArgs = preferedProtocol.serialize(obj);
 				final int len = objArgs.length;
+				
+				boolean wrap;
+				if (wrap = index > 0 && len != 0)
+					source.append('{');
 
-				StringBuilder sb = new StringBuilder(ImportsProvider.getAliasFor(args[0], obj.getClass()));
+				source.append(ImportsProvider.getAliasFor(args[0], obj.getClass()));
 				args = args.clone();
 				if (args[5] instanceof Byte && (byte) args[5] != 0) // Format
 				{
-					for (int i = 0, sizeEndl = 10000; i < len; i++) 
+					for (int i = 0; i < len; i++) 
 					{
-						if (sb.length() > sizeEndl)
+						if (i != 0 && i % 1000 == 0)
 						{
-							sb.append('\n'); 
+							source.append('\n'); 
 							for (int j = 0; j < tabs+1; j++) 
-								sb.append('\t');
-							sizeEndl += 10000;
+								source.append('\t');
 						}
 						else 
-							sb.append(' ');
+							source.append(' ');
 
 						if (args.length > 2)
 							args[2] = index + 1; // DO NOT TOUCH
-						sb.append(myHomeRegistry.toString(objArgs[i], args));
+						myHomeRegistry.toString(source, objArgs[i], args);
 					}
 				}
 				else
 				{
 					for (int i = 0; i < len; i++)
 					{
-						sb.append(' ');
+						source.append(' ');
 
 						if (args.length > 2)
 							args[2] = index + 1; // DO NOT TOUCH
-						sb.append(myHomeRegistry.toString(objArgs[i], args));
+						myHomeRegistry.toString(source, objArgs[i], args);
 					}
 				}
 
 				args[4] = oldObjectClass;
-				return index > 0 && len != 0 ? sb.insert(0, '{').append('}') : sb;
+				return wrap ? source.append('}') : source;
 			}
 			catch (Exception e)
 			{