1
/* Jackson JSON-processor.
3
* Copyright (c) 2007- Tatu Saloranta, tatu.saloranta@iki.fi
5
package com.fasterxml.jackson.core;
8
import java.math.BigDecimal;
9
import java.math.BigInteger;
11
import com.fasterxml.jackson.core.io.CharacterEscapes;
14
* Base class that defines public API for writing JSON content.
15
* Instances are created using factory methods of
16
* a {@link JsonFactory} instance.
18
* @author Tatu Saloranta
20
public abstract class JsonGenerator
21
implements Closeable, Flushable, // as of 2.1
25
* Enumeration that defines all togglable features for generators.
29
* Feature that determines whether generator will automatically
30
* close underlying output target that is NOT owned by the
32
* If disabled, calling application has to separately
33
* close the underlying {@link OutputStream} and {@link Writer}
34
* instances used to create the generator. If enabled, generator
35
* will handle closing, as long as generator itself gets closed:
36
* this happens when end-of-input is encountered, or generator
37
* is closed by a call to {@link JsonGenerator#close}.
39
* Feature is enabled by default.
41
AUTO_CLOSE_TARGET(true),
44
* Feature that determines what happens when the generator is
45
* closed while there are still unmatched
46
* {@link JsonToken#START_ARRAY} or {@link JsonToken#START_OBJECT}
47
* entries in output content. If enabled, such Array(s) and/or
48
* Object(s) are automatically closed; if disabled, nothing
51
* Feature is enabled by default.
53
AUTO_CLOSE_JSON_CONTENT(true),
56
* Feature that determines whether JSON Object field names are
57
* quoted using double-quotes, as specified by JSON specification
58
* or not. Ability to disable quoting was added to support use
59
* cases where they are not usually expected, which most commonly
60
* occurs when used straight from Javascript.
62
* Feature is enabled by default (since it is required by JSON specification).
64
QUOTE_FIELD_NAMES(true),
67
* Feature that determines whether "exceptional" (not real number)
68
* float/double values are output as quoted strings.
69
* The values checked are Double.Nan,
70
* Double.POSITIVE_INFINITY and Double.NEGATIVE_INIFINTY (and
71
* associated Float values).
72
* If feature is disabled, these numbers are still output using
73
* associated literal values, resulting in non-conformant
76
* Feature is enabled by default.
78
QUOTE_NON_NUMERIC_NUMBERS(true),
81
* Feature that forces all Java numbers to be written as JSON strings.
82
* Default state is 'false', meaning that Java numbers are to
83
* be serialized using basic numeric serialization (as JSON
84
* numbers, integral or floating point). If enabled, all such
85
* numeric values are instead written out as JSON Strings.
87
* One use case is to avoid problems with Javascript limitations:
88
* since Javascript standard specifies that all number handling
89
* should be done using 64-bit IEEE 754 floating point values,
90
* result being that some 64-bit integer values can not be
91
* accurately represent (as mantissa is only 51 bit wide).
93
* Feature is disabled by default.
95
WRITE_NUMBERS_AS_STRINGS(false),
98
* Feature that specifies that calls to {@link #flush} will cause
99
* matching <code>flush()</code> to underlying {@link OutputStream}
100
* or {@link Writer}; if disabled this will not be done.
101
* Main reason to disable this feature is to prevent flushing at
102
* generator level, if it is not possible to prevent method being
103
* called by other code (like <code>ObjectMapper</code> or third
106
* Feature is enabled by default.
108
FLUSH_PASSED_TO_STREAM(true),
111
* Feature that specifies that all characters beyond 7-bit ASCII
112
* range (i.e. code points of 128 and above) need to be output
113
* using format-specific escapes (for JSON, backslash escapes),
114
* if format uses escaping mechanisms (which is generally true
115
* for textual formats but not for binary formats).
117
* Feature is disabled by default.
119
ESCAPE_NON_ASCII(false),
123
private final boolean _defaultState;
125
private final int _mask;
128
* Method that calculates bit set (flags) of all features that
129
* are enabled by default.
131
public static int collectDefaults()
134
for (Feature f : values()) {
135
if (f.enabledByDefault()) {
136
flags |= f.getMask();
142
private Feature(boolean defaultState) {
143
_mask = (1 << ordinal());
144
_defaultState = defaultState;
147
public boolean enabledByDefault() { return _defaultState; }
148
public int getMask() { return _mask; }
152
/**********************************************************
154
/**********************************************************
158
* Object that handles pretty-printing (usually additional
159
* white space to make results more human-readable) during
160
* output. If null, no pretty-printing is done.
162
protected PrettyPrinter _cfgPrettyPrinter;
165
/**********************************************************
166
/* Construction, initialization
167
/**********************************************************
170
protected JsonGenerator() { }
173
* Method that can be called to set or reset the object to
174
* use for writing Java objects as JsonContent
175
* (using method {@link #writeObject}).
177
* @return Generator itself (this), to allow chaining
179
public abstract JsonGenerator setCodec(ObjectCodec oc);
182
* Method for accessing the object used for writing Java
183
* object as Json content
184
* (using method {@link #writeObject}).
186
public abstract ObjectCodec getCodec();
189
* Method to call to make this generator use specified schema.
190
* Method must be called before generating any content, right after instance
192
* Note that not all generators support schemas; and those that do usually only
193
* accept specific types of schemas: ones defined for data format this generator
196
* If generator does not support specified schema, {@link UnsupportedOperationException}
199
* @param schema Schema to use
201
* @throws UnsupportedOperationException if generator does not support schema
203
public void setSchema(FormatSchema schema)
205
throw new UnsupportedOperationException("Generator of type "+getClass().getName()+" does not support schema of type '"
206
+schema.getSchemaType()+"'");
210
* Method for accessing Schema that this parser uses, if any.
211
* Default implementation returns null.
215
public FormatSchema getSchema() {
220
* Method that can be used to verify that given schema can be used with
221
* this generator (using {@link #setSchema}).
223
* @param schema Schema to check
225
* @return True if this generator can use given schema; false if not
227
public boolean canUseSchema(FormatSchema schema) {
232
* Accessor for finding out version of the bundle that provided this generator instance.
235
public abstract Version version();
238
* Method that can be used to get access to object that is used
239
* as target for generated output; this is usually either
240
* {@link OutputStream} or {@link Writer}, depending on what
241
* generator was constructed with.
242
* Note that returned value may be null in some cases; including
243
* case where implementation does not want to exposed raw
245
* In cases where output has been decorated, object returned here
246
* is the decorated version; this allows some level of interaction
247
* between users of generator and decorator object.
249
* In general use of this accessor should be considered as
250
* "last effort", i.e. only used if no other mechanism is applicable.
252
public Object getOutputTarget() {
257
* Method that allows overriding String used for separating root-level
258
* JSON values (default is single space character)
260
* @param sep Separator to use, if any; null means that no separator is
261
* automatically added
265
public JsonGenerator setRootValueSeparator(SerializableString sep) {
266
throw new UnsupportedOperationException();
270
/**********************************************************
271
/* Public API, configuration
272
/**********************************************************
276
* Method for enabling specified parser features:
277
* check {@link Feature} for list of available features.
279
* @return Generator itself (this), to allow chaining
281
public abstract JsonGenerator enable(Feature f);
284
* Method for disabling specified features
285
* (check {@link Feature} for list of features)
287
* @return Generator itself (this), to allow chaining
289
public abstract JsonGenerator disable(Feature f);
292
* Method for enabling or disabling specified feature:
293
* check {@link Feature} for list of available features.
295
* @return Generator itself (this), to allow chaining
297
public final JsonGenerator configure(Feature f, boolean state)
308
* Method for checking whether given feature is enabled.
309
* Check {@link Feature} for list of available features.
311
public abstract boolean isEnabled(Feature f);
314
/**********************************************************
315
/* Configuring generator
316
/**********************************************************
320
* Method for setting a custom pretty printer, which is usually
321
* used to add indentation for improved human readability.
322
* By default, generator does not do pretty printing.
324
* To use the default pretty printer that comes with core
325
* Jackson distribution, call {@link #useDefaultPrettyPrinter}
328
* @return Generator itself (this), to allow chaining
330
public JsonGenerator setPrettyPrinter(PrettyPrinter pp) {
331
_cfgPrettyPrinter = pp;
336
* Accessor for checking whether this generator has a configured
337
* {@link PrettyPrinter}; returns it if so, null if none configured.
341
public PrettyPrinter getPrettyPrinter() {
342
return _cfgPrettyPrinter;
346
* Convenience method for enabling pretty-printing using
347
* the default pretty printer
348
* ({@link com.fasterxml.jackson.core.util.DefaultPrettyPrinter}).
350
* @return Generator itself (this), to allow chaining
352
public abstract JsonGenerator useDefaultPrettyPrinter();
355
* Method that can be called to request that generator escapes
356
* all character codes above specified code point (if positive value);
357
* or, to not escape any characters except for ones that must be
358
* escaped for the data format (if -1).
359
* To force escaping of all non-ASCII characters, for example,
360
* this method would be called with value of 127.
362
* Note that generators are NOT required to support setting of value
363
* higher than 127, because there are other ways to affect quoting
364
* (or lack thereof) of character codes between 0 and 127.
365
* Not all generators support concept of escaping, either; if so,
366
* calling this method will have no effect.
368
* Default implementation does nothing; sub-classes need to redefine
369
* it according to rules of supported data format.
371
* @param charCode Either -1 to indicate that no additional escaping
372
* is to be done; or highest code point not to escape (meaning higher
373
* ones will be), if positive value.
375
public JsonGenerator setHighestNonEscapedChar(int charCode) {
380
* Accessor method for testing what is the highest unescaped character
381
* configured for this generator. This may be either positive value
382
* (when escaping configuration has been set and is in effect), or
383
* 0 to indicate that no additional escaping is in effect.
384
* Some generators may not support additional escaping: for example,
385
* generators for binary formats that do not use escaping should
388
* @return Currently active limitation for highest non-escaped character,
389
* if defined; or -1 to indicate no additional escaping is performed.
391
public int getHighestEscapedChar() {
396
* Method for accessing custom escapes factory uses for {@link JsonGenerator}s
399
public CharacterEscapes getCharacterEscapes() {
404
* Method for defining custom escapes factory uses for {@link JsonGenerator}s
407
public JsonGenerator setCharacterEscapes(CharacterEscapes esc) {
412
/**********************************************************
413
/* Public API, write methods, structural
414
/**********************************************************
418
* Method for writing starting marker of a JSON Array value
419
* (character '['; plus possible white space decoration
420
* if pretty-printing is enabled).
422
* Array values can be written in any context where values
423
* are allowed: meaning everywhere except for when
424
* a field name is expected.
426
public abstract void writeStartArray()
427
throws IOException, JsonGenerationException;
430
* Method for writing closing marker of a JSON Array value
431
* (character ']'; plus possible white space decoration
432
* if pretty-printing is enabled).
434
* Marker can be written if the innermost structured type
437
public abstract void writeEndArray()
438
throws IOException, JsonGenerationException;
441
* Method for writing starting marker of a JSON Object value
442
* (character '{'; plus possible white space decoration
443
* if pretty-printing is enabled).
445
* Object values can be written in any context where values
446
* are allowed: meaning everywhere except for when
447
* a field name is expected.
449
public abstract void writeStartObject()
450
throws IOException, JsonGenerationException;
453
* Method for writing closing marker of a JSON Object value
454
* (character '}'; plus possible white space decoration
455
* if pretty-printing is enabled).
457
* Marker can be written if the innermost structured type
458
* is Object, and the last written event was either a
459
* complete value, or START-OBJECT marker (see JSON specification
462
public abstract void writeEndObject()
463
throws IOException, JsonGenerationException;
466
* Method for writing a field name (JSON String surrounded by
467
* double quotes: syntactically identical to a JSON String value),
468
* possibly decorated by white space if pretty-printing is enabled.
470
* Field names can only be written in Object context (check out
471
* JSON specification for details), when field name is expected
472
* (field names alternate with values).
474
public abstract void writeFieldName(String name)
475
throws IOException, JsonGenerationException;
478
* Method similar to {@link #writeFieldName(String)}, main difference
479
* being that it may perform better as some of processing (such as
480
* quoting of certain characters, or encoding into external encoding
481
* if supported by generator) can be done just once and reused for
484
* Default implementation simple uses unprocessed name container in
485
* serialized String; implementations are strongly encouraged to make
486
* use of more efficient methods argument object has.
488
public abstract void writeFieldName(SerializableString name)
489
throws IOException, JsonGenerationException;
492
/**********************************************************
493
/* Public API, write methods, text/String values
494
/**********************************************************
498
* Method for outputting a String value. Depending on context
499
* this means either array element, (object) field value or
500
* a stand alone String; but in all cases, String will be
501
* surrounded in double quotes, and contents will be properly
502
* escaped as required by JSON specification.
504
public abstract void writeString(String text)
505
throws IOException, JsonGenerationException;
508
* Method for outputting a String value. Depending on context
509
* this means either array element, (object) field value or
510
* a stand alone String; but in all cases, String will be
511
* surrounded in double quotes, and contents will be properly
512
* escaped as required by JSON specification.
514
public abstract void writeString(char[] text, int offset, int len)
515
throws IOException, JsonGenerationException;
518
* Method similar to {@link #writeString(String)}, but that takes
519
* {@link SerializableString} which can make this potentially
520
* more efficient to call as generator may be able to reuse
521
* quoted and/or encoded representation.
523
* Default implementation just calls {@link #writeString(String)};
524
* sub-classes should override it with more efficient implementation
527
public abstract void writeString(SerializableString text)
528
throws IOException, JsonGenerationException;
531
* Method similar to {@link #writeString(String)} but that takes as
532
* its input a UTF-8 encoded String that is to be output as-is, without additional
533
* escaping (type of which depends on data format; backslashes for JSON).
534
* However, quoting that data format requires (like double-quotes for JSON) will be added
535
* around the value if and as necessary.
537
* Note that some backends may choose not to support this method: for
538
* example, if underlying destination is a {@link java.io.Writer}
539
* using this method would require UTF-8 decoding.
540
* If so, implementation may instead choose to throw a
541
* {@link UnsupportedOperationException} due to ineffectiveness
542
* of having to decode input.
544
public abstract void writeRawUTF8String(byte[] text, int offset, int length)
545
throws IOException, JsonGenerationException;
548
* Method similar to {@link #writeString(String)} but that takes as its input
549
* a UTF-8 encoded String which has <b>not</b> been escaped using whatever
550
* escaping scheme data format requires (for JSON that is backslash-escaping
551
* for control characters and double-quotes; for other formats something else).
552
* This means that textual JSON backends need to check if value needs
553
* JSON escaping, but otherwise can just be copied as is to output.
554
* Also, quoting that data format requires (like double-quotes for JSON) will be added
555
* around the value if and as necessary.
557
* Note that some backends may choose not to support this method: for
558
* example, if underlying destination is a {@link java.io.Writer}
559
* using this method would require UTF-8 decoding.
561
* generator implementation may instead choose to throw a
562
* {@link UnsupportedOperationException} due to ineffectiveness
563
* of having to decode input.
565
public abstract void writeUTF8String(byte[] text, int offset, int length)
566
throws IOException, JsonGenerationException;
569
/**********************************************************
570
/* Public API, write methods, binary/raw content
571
/**********************************************************
575
* Method that will force generator to copy
576
* input text verbatim with <b>no</b> modifications (including
577
* that no escaping is done and no separators are added even
578
* if context [array, object] would otherwise require such).
579
* If such separators are desired, use
580
* {@link #writeRawValue(String)} instead.
582
* Note that not all generator implementations necessarily support
583
* such by-pass methods: those that do not will throw
584
* {@link UnsupportedOperationException}.
586
public abstract void writeRaw(String text)
587
throws IOException, JsonGenerationException;
590
* Method that will force generator to copy
591
* input text verbatim with <b>no</b> modifications (including
592
* that no escaping is done and no separators are added even
593
* if context [array, object] would otherwise require such).
594
* If such separators are desired, use
595
* {@link #writeRawValue(String)} instead.
597
* Note that not all generator implementations necessarily support
598
* such by-pass methods: those that do not will throw
599
* {@link UnsupportedOperationException}.
601
public abstract void writeRaw(String text, int offset, int len)
602
throws IOException, JsonGenerationException;
605
* Method that will force generator to copy
606
* input text verbatim with <b>no</b> modifications (including
607
* that no escaping is done and no separators are added even
608
* if context [array, object] would otherwise require such).
609
* If such separators are desired, use
610
* {@link #writeRawValue(String)} instead.
612
* Note that not all generator implementations necessarily support
613
* such by-pass methods: those that do not will throw
614
* {@link UnsupportedOperationException}.
616
public abstract void writeRaw(char[] text, int offset, int len)
617
throws IOException, JsonGenerationException;
620
* Method that will force generator to copy
621
* input text verbatim with <b>no</b> modifications (including
622
* that no escaping is done and no separators are added even
623
* if context [array, object] would otherwise require such).
624
* If such separators are desired, use
625
* {@link #writeRawValue(String)} instead.
627
* Note that not all generator implementations necessarily support
628
* such by-pass methods: those that do not will throw
629
* {@link UnsupportedOperationException}.
631
public abstract void writeRaw(char c)
632
throws IOException, JsonGenerationException;
635
* Method that will force generator to copy
636
* input text verbatim with <b>no</b> modifications (including
637
* that no escaping is done and no separators are added even
638
* if context [array, object] would otherwise require such).
639
* If such separators are desired, use
640
* {@link #writeRawValue(String)} instead.
642
* Note that not all generator implementations necessarily support
643
* such by-pass methods: those that do not will throw
644
* {@link UnsupportedOperationException}.
646
* The default implementation delegates to {@link #writeRaw(String)};
647
* other backends that support raw inclusion of text are encouraged
648
* to implement it in more efficient manner (especially if they
649
* use UTF-8 encoding).
653
public void writeRaw(SerializableString raw)
654
throws IOException, JsonGenerationException {
655
writeRaw(raw.getValue());
659
* Method that will force generator to copy
660
* input text verbatim without any modifications, but assuming
661
* it must constitute a single legal JSON value (number, string,
662
* boolean, null, Array or List). Assuming this, proper separators
663
* are added if and as needed (comma or colon), and generator
664
* state updated to reflect this.
666
public abstract void writeRawValue(String text)
667
throws IOException, JsonGenerationException;
669
public abstract void writeRawValue(String text, int offset, int len)
670
throws IOException, JsonGenerationException;
672
public abstract void writeRawValue(char[] text, int offset, int len)
673
throws IOException, JsonGenerationException;
676
* Method that will output given chunk of binary data as base64
677
* encoded, as a complete String value (surrounded by double quotes).
678
* This method defaults
680
* Note: because Json Strings can not contain unescaped linefeeds,
681
* if linefeeds are included (as per last argument), they must be
682
* escaped. This adds overhead for decoding without improving
684
* Alternatively if linefeeds are not included,
685
* resulting String value may violate the requirement of base64
686
* RFC which mandates line-length of 76 characters and use of
687
* linefeeds. However, all {@link JsonParser} implementations
688
* are required to accept such "long line base64"; as do
689
* typical production-level base64 decoders.
691
* @param b64variant Base64 variant to use: defines details such as
692
* whether padding is used (and if so, using which character);
693
* what is the maximum line length before adding linefeed,
694
* and also the underlying alphabet to use.
696
public abstract void writeBinary(Base64Variant b64variant,
697
byte[] data, int offset, int len)
698
throws IOException, JsonGenerationException;
701
* Similar to {@link #writeBinary(Base64Variant,byte[],int,int)},
702
* but default to using the Jackson default Base64 variant
703
* (which is {@link Base64Variants#MIME_NO_LINEFEEDS}).
705
public void writeBinary(byte[] data, int offset, int len)
706
throws IOException, JsonGenerationException
708
writeBinary(Base64Variants.getDefaultVariant(), data, offset, len);
712
* Similar to {@link #writeBinary(Base64Variant,byte[],int,int)},
713
* but assumes default to using the Jackson default Base64 variant
714
* (which is {@link Base64Variants#MIME_NO_LINEFEEDS}). Also
715
* assumes that whole byte array is to be output.
717
public void writeBinary(byte[] data)
718
throws IOException, JsonGenerationException
720
writeBinary(Base64Variants.getDefaultVariant(), data, 0, data.length);
724
* Similar to {@link #writeBinary(Base64Variant,InputStream,int)},
725
* but assumes default to using the Jackson default Base64 variant
726
* (which is {@link Base64Variants#MIME_NO_LINEFEEDS}).
728
* @param data InputStream to use for reading binary data to write.
729
* Will not be closed after successful write operation
730
* @param dataLength (optional) number of bytes that will be available;
731
* or -1 to be indicate it is not known. Note that implementations
732
* need not support cases where length is not known in advance; this
733
* depends on underlying data format: JSON output does NOT require length,
736
public int writeBinary(InputStream data, int dataLength)
737
throws IOException, JsonGenerationException {
738
return writeBinary(Base64Variants.getDefaultVariant(), data, dataLength);
742
* Method similar to {@link #writeBinary(Base64Variant,byte[],int,int)},
743
* but where input is provided through a stream, allowing for incremental
744
* writes without holding the whole input in memory.
746
* @param b64variant Base64 variant to use
747
* @param data InputStream to use for reading binary data to write.
748
* Will not be closed after successful write operation
749
* @param dataLength (optional) number of bytes that will be available;
750
* or -1 to be indicate it is not known.
751
* If a positive length is given, <code>data</code> MUST provide at least
752
* that many bytes: if not, an exception will be thrown.
753
* Note that implementations
754
* need not support cases where length is not known in advance; this
755
* depends on underlying data format: JSON output does NOT require length,
758
* @return Number of bytes read from <code>data</code> and written as binary payload
762
public abstract int writeBinary(Base64Variant b64variant,
763
InputStream data, int dataLength)
764
throws IOException, JsonGenerationException;
767
/**********************************************************
768
/* Public API, write methods, other value types
769
/**********************************************************
773
* Method for outputting given value as Json number.
774
* Can be called in any context where a value is expected
775
* (Array value, Object field value, root-level value).
776
* Additional white space may be added around the value
777
* if pretty-printing is enabled.
781
public void writeNumber(short v) throws IOException, JsonGenerationException {
782
writeNumber((int) v);
786
* Method for outputting given value as Json number.
787
* Can be called in any context where a value is expected
788
* (Array value, Object field value, root-level value).
789
* Additional white space may be added around the value
790
* if pretty-printing is enabled.
792
public abstract void writeNumber(int v)
793
throws IOException, JsonGenerationException;
796
* Method for outputting given value as Json number.
797
* Can be called in any context where a value is expected
798
* (Array value, Object field value, root-level value).
799
* Additional white space may be added around the value
800
* if pretty-printing is enabled.
802
public abstract void writeNumber(long v)
803
throws IOException, JsonGenerationException;
806
* Method for outputting given value as Json number.
807
* Can be called in any context where a value is expected
808
* (Array value, Object field value, root-level value).
809
* Additional white space may be added around the value
810
* if pretty-printing is enabled.
812
public abstract void writeNumber(BigInteger v)
813
throws IOException, JsonGenerationException;
816
* Method for outputting indicate Json numeric value.
817
* Can be called in any context where a value is expected
818
* (Array value, Object field value, root-level value).
819
* Additional white space may be added around the value
820
* if pretty-printing is enabled.
822
public abstract void writeNumber(double d)
823
throws IOException, JsonGenerationException;
826
* Method for outputting indicate Json numeric value.
827
* Can be called in any context where a value is expected
828
* (Array value, Object field value, root-level value).
829
* Additional white space may be added around the value
830
* if pretty-printing is enabled.
832
public abstract void writeNumber(float f)
833
throws IOException, JsonGenerationException;
836
* Method for outputting indicate Json numeric value.
837
* Can be called in any context where a value is expected
838
* (Array value, Object field value, root-level value).
839
* Additional white space may be added around the value
840
* if pretty-printing is enabled.
842
public abstract void writeNumber(BigDecimal dec)
843
throws IOException, JsonGenerationException;
846
* Write method that can be used for custom numeric types that can
847
* not be (easily?) converted to "standard" Java number types.
848
* Because numbers are not surrounded by double quotes, regular
849
* {@link #writeString} method can not be used; nor
850
* {@link #writeRaw} because that does not properly handle
851
* value separators needed in Array or Object contexts.
853
* Note: because of lack of type safety, some generator
854
* implementations may not be able to implement this
855
* method. For example, if a binary json format is used,
856
* it may require type information for encoding; similarly
857
* for generator-wrappers around Java objects or Json nodes.
858
* If implementation does not implement this method,
859
* it needs to throw {@link UnsupportedOperationException}.
861
public abstract void writeNumber(String encodedValue)
862
throws IOException, JsonGenerationException,
863
UnsupportedOperationException;
866
* Method for outputting literal Json boolean value (one of
867
* Strings 'true' and 'false').
868
* Can be called in any context where a value is expected
869
* (Array value, Object field value, root-level value).
870
* Additional white space may be added around the value
871
* if pretty-printing is enabled.
873
public abstract void writeBoolean(boolean state)
874
throws IOException, JsonGenerationException;
877
* Method for outputting literal Json null value.
878
* Can be called in any context where a value is expected
879
* (Array value, Object field value, root-level value).
880
* Additional white space may be added around the value
881
* if pretty-printing is enabled.
883
public abstract void writeNull()
884
throws IOException, JsonGenerationException;
887
/**********************************************************
888
/* Public API, write methods, serializing Java objects
889
/**********************************************************
893
* Method for writing given Java object (POJO) as Json.
894
* Exactly how the object gets written depends on object
895
* in question (ad on codec, its configuration); for most
896
* beans it will result in Json object, but for others Json
897
* array, or String or numeric value (and for nulls, Json
899
* <b>NOTE</b>: generator must have its <b>object codec</b>
900
* set to non-null value; for generators created by a mapping
901
* factory this is the case, for others not.
903
public abstract void writeObject(Object pojo)
904
throws IOException, JsonProcessingException;
907
* Method for writing given JSON tree (expressed as a tree
908
* where given JsonNode is the root) using this generator.
909
* This will generally just call
910
* {@link #writeObject} with given node, but is added
911
* for convenience and to make code more explicit in cases
912
* where it deals specifically with trees.
914
public abstract void writeTree(TreeNode rootNode)
915
throws IOException, JsonProcessingException;
918
/**********************************************************
919
/* Public API, convenience field write methods
920
/**********************************************************
924
* Convenience method for outputting a field entry ("member")
925
* that has a String value. Equivalent to:
927
* writeFieldName(fieldName);
928
* writeString(value);
931
* Note: many performance-sensitive implementations override this method
933
public void writeStringField(String fieldName, String value)
934
throws IOException, JsonGenerationException
936
writeFieldName(fieldName);
941
* Convenience method for outputting a field entry ("member")
942
* that has a boolean value. Equivalent to:
944
* writeFieldName(fieldName);
945
* writeBoolean(value);
948
public final void writeBooleanField(String fieldName, boolean value)
949
throws IOException, JsonGenerationException
951
writeFieldName(fieldName);
956
* Convenience method for outputting a field entry ("member")
957
* that has JSON literal value null. Equivalent to:
959
* writeFieldName(fieldName);
963
public final void writeNullField(String fieldName)
964
throws IOException, JsonGenerationException
966
writeFieldName(fieldName);
970
* Convenience method for outputting a field entry ("member")
971
* that has the specified numeric value. Equivalent to:
973
* writeFieldName(fieldName);
974
* writeNumber(value);
977
public final void writeNumberField(String fieldName, int value)
978
throws IOException, JsonGenerationException
980
writeFieldName(fieldName);
985
* Convenience method for outputting a field entry ("member")
986
* that has the specified numeric value. Equivalent to:
988
* writeFieldName(fieldName);
989
* writeNumber(value);
992
public final void writeNumberField(String fieldName, long value)
993
throws IOException, JsonGenerationException
995
writeFieldName(fieldName);
1000
* Convenience method for outputting a field entry ("member")
1001
* that has the specified numeric value. Equivalent to:
1003
* writeFieldName(fieldName);
1004
* writeNumber(value);
1007
public final void writeNumberField(String fieldName, double value)
1008
throws IOException, JsonGenerationException
1010
writeFieldName(fieldName);
1015
* Convenience method for outputting a field entry ("member")
1016
* that has the specified numeric value. Equivalent to:
1018
* writeFieldName(fieldName);
1019
* writeNumber(value);
1022
public final void writeNumberField(String fieldName, float value)
1023
throws IOException, JsonGenerationException
1025
writeFieldName(fieldName);
1030
* Convenience method for outputting a field entry ("member")
1031
* that has the specified numeric value.
1034
* writeFieldName(fieldName);
1035
* writeNumber(value);
1038
public final void writeNumberField(String fieldName, BigDecimal value)
1039
throws IOException, JsonGenerationException
1041
writeFieldName(fieldName);
1046
* Convenience method for outputting a field entry ("member")
1047
* that contains specified data in base64-encoded form.
1050
* writeFieldName(fieldName);
1051
* writeBinary(value);
1054
public final void writeBinaryField(String fieldName, byte[] data)
1055
throws IOException, JsonGenerationException
1057
writeFieldName(fieldName);
1062
* Convenience method for outputting a field entry ("member")
1063
* (that will contain a JSON Array value), and the START_ARRAY marker.
1066
* writeFieldName(fieldName);
1067
* writeStartArray();
1070
* Note: caller still has to take care to close the array
1071
* (by calling {#link #writeEndArray}) after writing all values
1072
* of the value Array.
1074
public final void writeArrayFieldStart(String fieldName)
1075
throws IOException, JsonGenerationException
1077
writeFieldName(fieldName);
1082
* Convenience method for outputting a field entry ("member")
1083
* (that will contain a JSON Object value), and the START_OBJECT marker.
1086
* writeFieldName(fieldName);
1087
* writeStartObject();
1090
* Note: caller still has to take care to close the Object
1091
* (by calling {#link #writeEndObject}) after writing all
1092
* entries of the value Object.
1094
public final void writeObjectFieldStart(String fieldName)
1095
throws IOException, JsonGenerationException
1097
writeFieldName(fieldName);
1102
* Convenience method for outputting a field entry ("member")
1103
* that has contents of specific Java object as its value.
1106
* writeFieldName(fieldName);
1107
* writeObject(pojo);
1110
public final void writeObjectField(String fieldName, Object pojo)
1111
throws IOException, JsonProcessingException
1113
writeFieldName(fieldName);
1118
/**********************************************************
1119
/* Public API, copy-through methods
1120
/**********************************************************
1124
* Method for copying contents of the current event that
1125
* the given parser instance points to.
1126
* Note that the method <b>will not</b> copy any other events,
1127
* such as events contained within Json Array or Object structures.
1129
* Calling this method will not advance the given
1130
* parser, although it may cause parser to internally process
1131
* more data (if it lazy loads contents of value events, for example)
1133
public abstract void copyCurrentEvent(JsonParser jp)
1134
throws IOException, JsonProcessingException;
1137
* Method for copying contents of the current event
1138
* <b>and following events that it encloses</b>
1139
* the given parser instance points to.
1141
* So what constitutes enclosing? Here is the list of
1142
* events that have associated enclosed events that will
1145
* <li>{@link JsonToken#START_OBJECT}:
1146
* all events up to and including matching (closing)
1147
* {@link JsonToken#END_OBJECT} will be copied
1149
* <li>{@link JsonToken#START_ARRAY}
1150
* all events up to and including matching (closing)
1151
* {@link JsonToken#END_ARRAY} will be copied
1153
* <li>{@link JsonToken#FIELD_NAME} the logical value (which
1154
* can consist of a single scalar value; or a sequence of related
1155
* events for structured types (Json Arrays, Objects)) will
1156
* be copied along with the name itself. So essentially the
1157
* whole <b>field entry</b> (name and value) will be copied.
1161
* After calling this method, parser will point to the
1162
* <b>last event</b> that was copied. This will either be
1163
* the event parser already pointed to (if there were no
1164
* enclosed events), or the last enclosed event copied.
1166
public abstract void copyCurrentStructure(JsonParser jp)
1167
throws IOException, JsonProcessingException;
1170
/**********************************************************
1171
/* Public API, context access
1172
/**********************************************************
1176
* @return Context object that can give information about logical
1177
* position within generated json content.
1179
public abstract JsonStreamContext getOutputContext();
1182
/**********************************************************
1183
/* Public API, buffer handling
1184
/**********************************************************
1188
* Method called to flush any buffered content to the underlying
1189
* target (output stream, writer), and to flush the target itself
1193
public abstract void flush() throws IOException;
1196
* Method that can be called to determine whether this generator
1197
* is closed or not. If it is closed, no more output can be done.
1199
public abstract boolean isClosed();
1202
/**********************************************************
1203
/* Closeable implementation
1204
/**********************************************************
1208
* Method called to close this generator, so that no more content
1211
* Whether the underlying target (stream, writer) gets closed depends
1212
* on whether this generator either manages the target (i.e. is the
1213
* only one with access to the target -- case if caller passes a
1214
* reference to the resource such as File, but not stream); or
1215
* has feature {@link Feature#AUTO_CLOSE_TARGET} enabled.
1216
* If either of above is true, the target is also closed. Otherwise
1217
* (not managing, feature not enabled), target is not closed.
1220
public abstract void close() throws IOException;
added
removed
src/main/java/com/fasterxml/jackson/core/JsonGenerator.java
