Merge branch '2.10'

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/core/JsonGenerator.java

@@ -28,17 +28,17 @@ public abstract class JsonGenerator
     implements Closeable, Flushable, Versioned
 {
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Construction, initialization
-    /**********************************************************
+    /**********************************************************************
      */
 
     protected JsonGenerator() { }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Versioned
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -48,9 +48,9 @@ protected JsonGenerator() { }
     public abstract Version version();
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, output configuration, state access
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -130,9 +130,9 @@ public int getOutputBuffered() {
     public abstract void setCurrentValue(Object v);
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, Feature configuration
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -189,9 +189,9 @@ public final JsonGenerator configure(StreamWriteFeature f, boolean state) {
     public abstract int formatWriteFeatures();
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, Schema configuration
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -281,9 +281,9 @@ public void setSchema(FormatSchema schema) {
     public JsonGenerator setCharacterEscapes(CharacterEscapes esc) { return this; }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, capability introspection methods
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -355,9 +355,9 @@ public void setSchema(FormatSchema schema) {
     public boolean canWriteFormattedNumbers() { return false; }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, write methods, structural
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -414,7 +414,7 @@ public void writeStartArray(int size) throws IOException {
     public abstract void writeEndArray() throws IOException;
 
     /**
-     * Method for writing starting marker of a JSON Object value
+     * Method for writing starting marker of an Object value
      * (character '{'; plus possible white space decoration
      * if pretty-printing is enabled).
      *<p>
@@ -425,10 +425,9 @@ public void writeStartArray(int size) throws IOException {
     public abstract void writeStartObject() throws IOException;
 
     /**
-     * Method for writing starting marker of a JSON Object value
-     * (character '{'; plus possible white space decoration
-     * if pretty-printing is enabled), to represent Java given
-     * as the argument. Argument is offered as metadata, but more
+     * Method for writing starting marker of an Object value
+     * to represent the given Java Object value.
+     * Argument is offered as metadata, but more
      * importantly it should be assigned as the "current value"
      * for the Object content that gets constructed and initialized.
      *<p>
@@ -439,7 +438,27 @@ public void writeStartArray(int size) throws IOException {
     public abstract void writeStartObject(Object forValue) throws IOException;
 
     /**
-     * Method for writing closing marker of a JSON Object value
+     * Method for writing starting marker of an Object value
+     * to represent the given Java Object value.
+     * Argument is offered as metadata, but more
+     * importantly it should be assigned as the "current value"
+     * for the Object content that gets constructed and initialized.
+     * In addition, caller knows number of key/value pairs ("properties")
+     * that will get written for the Object value: this is relevant for
+     * some format backends (but not, as an example, for JSON).
+     *<p>
+     * Object values can be written in any context where values
+     * are allowed: meaning everywhere except for when
+     * a field name is expected.
+     */
+    public void writeStartObject(Object forValue, int size) throws IOException
+    {
+        writeStartObject();
+        setCurrentValue(forValue);
+    }
+
+    /**
+     * Method for writing closing marker of an Object value
      * (character '}'; plus possible white space decoration
      * if pretty-printing is enabled).
      *<p>
@@ -487,9 +506,9 @@ public void writeFieldId(long id) throws IOException {
     }
 
     /*
-    /**********************************************************
-    /* Public API, write methods, scalar arrays (2.8)
-    /**********************************************************
+    /**********************************************************************
+    /* Public API, write methods, scalar arrays
+    /**********************************************************************
      */
 
     /**
@@ -507,7 +526,7 @@ public void writeArray(int[] array, int offset, int length) throws IOException
             throw new IllegalArgumentException("null array");
         }
         _verifyOffsets(array.length, offset, length);
-        writeStartArray();
+        writeStartArray(array, length);
         for (int i = offset, end = offset+length; i < end; ++i) {
             writeNumber(array[i]);
         }
@@ -529,7 +548,7 @@ public void writeArray(long[] array, int offset, int length) throws IOException
             throw new IllegalArgumentException("null array");
         }
         _verifyOffsets(array.length, offset, length);
-        writeStartArray();
+        writeStartArray(array, length);
         for (int i = offset, end = offset+length; i < end; ++i) {
             writeNumber(array[i]);
         }
@@ -551,17 +570,17 @@ public void writeArray(double[] array, int offset, int length) throws IOExceptio
             throw new IllegalArgumentException("null array");
         }
         _verifyOffsets(array.length, offset, length);
-        writeStartArray();
+        writeStartArray(array, length);
         for (int i = offset, end = offset+length; i < end; ++i) {
             writeNumber(array[i]);
         }
         writeEndArray();
     }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, write methods, text/String values
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -648,9 +667,9 @@ public abstract void writeUTF8String(byte[] text, int offset, int length)
         throws IOException;
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, write methods, binary/raw content
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -838,9 +857,9 @@ public abstract int writeBinary(Base64Variant bv,
             InputStream data, int dataLength) throws IOException;
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, write methods, numeric
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -944,9 +963,9 @@ public abstract int writeBinary(Base64Variant bv,
     public abstract void writeNumber(String encodedValue) throws IOException;
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, write methods, other value types
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -986,11 +1005,11 @@ public void writeEmbeddedObject(Object object) throws IOException {
                 +object.getClass().getName(),
                 this);
     }
-    
+
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, write methods, Native Ids (type, object)
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -1140,9 +1159,9 @@ public WritableTypeId writeTypeSuffix(WritableTypeId typeIdDef) throws IOExcepti
     }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, write methods, serializing Java objects
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -1162,9 +1181,9 @@ public WritableTypeId writeTypeSuffix(WritableTypeId typeIdDef) throws IOExcepti
     public abstract void writeTree(TreeNode rootNode) throws IOException;
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, convenience field write methods
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -1308,7 +1327,7 @@ public final void writeArrayFieldStart(String fieldName) throws IOException {
 
     /**
      * Convenience method for outputting a field entry ("member")
-     * (that will contain a JSON Object value), and the START_OBJECT marker.
+     * (that will contain an Object value), and the START_OBJECT marker.
      * Equivalent to:
      *<pre>
      *  writeFieldName(fieldName);
@@ -1346,11 +1365,11 @@ public final void writeObjectField(String fieldName, Object pojo) throws IOExcep
      * Default implementation does nothing.
      */
     public void writeOmittedField(String fieldName) throws IOException { }
-    
+
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, copy-through methods
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -1502,9 +1521,9 @@ public void copyCurrentStructure(JsonParser p) throws IOException
     }
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Public API, buffer handling
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -1522,9 +1541,9 @@ public void copyCurrentStructure(JsonParser p) throws IOException
     public abstract boolean isClosed();
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Closeable implementation
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**
@@ -1543,9 +1562,9 @@ public void copyCurrentStructure(JsonParser p) throws IOException
     public abstract void close() throws IOException;
 
     /*
-    /**********************************************************
+    /**********************************************************************
     /* Helper methods for sub-classes
-    /**********************************************************
+    /**********************************************************************
      */
 
     /**