Tatu Saloranta | 68bb83d | 2013-04-19 10:41:15 -0700 | [diff] [blame] | 1 | /* Jackson JSON-processor. |
| 2 | * |
| 3 | * Copyright (c) 2007- Tatu Saloranta, tatu.saloranta@iki.fi |
| 4 | */ |
| 5 | |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 6 | package com.fasterxml.jackson.core; |
| 7 | |
| 8 | import java.io.IOException; |
| 9 | |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 10 | import com.fasterxml.jackson.core.io.SerializedString; |
| 11 | import com.fasterxml.jackson.core.util.Separators; |
| 12 | |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 13 | /** |
| 14 | * Interface for objects that implement pretty printer functionality, such |
| 15 | * as indentation. |
| 16 | * Pretty printers are used to add white space in output JSON content, |
| 17 | * to make results more human readable. Usually this means things like adding |
| 18 | * linefeeds and indentation. |
Tatu Saloranta | d67df9b | 2012-08-01 23:32:46 -0700 | [diff] [blame] | 19 | *<p> |
| 20 | * Note: since Jackson 2.1, stateful implementations MUST implement |
| 21 | * {@link com.fasterxml.jackson.core.util.Instantiatable} interface, |
| 22 | * to allow for constructing per-generation instances and avoid |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 23 | * state corruption. |
Tatu Saloranta | d67df9b | 2012-08-01 23:32:46 -0700 | [diff] [blame] | 24 | * Stateless implementations need not do this; but those are less common. |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 25 | */ |
| 26 | public interface PrettyPrinter |
| 27 | { |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 28 | /** |
| 29 | * @since 2.9 |
| 30 | */ |
| 31 | public final static Separators DEFAULT_SEPARATORS = Separators.createDefaultInstance(); |
| 32 | |
| 33 | /** |
| 34 | * Default String used for separating root values is single space. |
| 35 | * |
| 36 | * @since 2.9 |
| 37 | */ |
| 38 | public final static SerializedString DEFAULT_ROOT_VALUE_SEPARATOR = new SerializedString(" "); |
| 39 | |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 40 | /* |
| 41 | /********************************************************** |
| 42 | /* First methods that act both as events, and expect |
| 43 | /* output for correct functioning (i.e something gets |
| 44 | /* output even when not pretty-printing) |
| 45 | /********************************************************** |
| 46 | */ |
| 47 | |
| 48 | // // // Root-level handling: |
| 49 | |
| 50 | /** |
| 51 | * Method called after a root-level value has been completely |
| 52 | * output, and before another value is to be output. |
| 53 | *<p> |
| 54 | * Default |
| 55 | * handling (without pretty-printing) will output a space, to |
| 56 | * allow values to be parsed correctly. Pretty-printer is |
| 57 | * to output some other suitable and nice-looking separator |
| 58 | * (tab(s), space(s), linefeed(s) or any combination thereof). |
| 59 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 60 | void writeRootValueSeparator(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 61 | |
| 62 | // // Object handling |
| 63 | |
| 64 | /** |
| 65 | * Method called when an Object value is to be output, before |
| 66 | * any fields are output. |
| 67 | *<p> |
| 68 | * Default handling (without pretty-printing) will output |
| 69 | * the opening curly bracket. |
| 70 | * Pretty-printer is |
| 71 | * to output a curly bracket as well, but can surround that |
| 72 | * with other (white-space) decoration. |
| 73 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 74 | void writeStartObject(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 75 | |
| 76 | /** |
| 77 | * Method called after an Object value has been completely output |
| 78 | * (minus closing curly bracket). |
| 79 | *<p> |
| 80 | * Default handling (without pretty-printing) will output |
| 81 | * the closing curly bracket. |
| 82 | * Pretty-printer is |
| 83 | * to output a curly bracket as well, but can surround that |
| 84 | * with other (white-space) decoration. |
| 85 | * |
| 86 | * @param nrOfEntries Number of direct members of the array that |
| 87 | * have been output |
| 88 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 89 | void writeEndObject(JsonGenerator gen, int nrOfEntries) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 90 | |
| 91 | /** |
| 92 | * Method called after an object entry (field:value) has been completely |
| 93 | * output, and before another value is to be output. |
| 94 | *<p> |
| 95 | * Default handling (without pretty-printing) will output a single |
| 96 | * comma to separate the two. Pretty-printer is |
| 97 | * to output a comma as well, but can surround that with other |
| 98 | * (white-space) decoration. |
| 99 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 100 | void writeObjectEntrySeparator(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 101 | |
| 102 | /** |
| 103 | * Method called after an object field has been output, but |
| 104 | * before the value is output. |
| 105 | *<p> |
| 106 | * Default handling (without pretty-printing) will output a single |
| 107 | * colon to separate the two. Pretty-printer is |
| 108 | * to output a colon as well, but can surround that with other |
| 109 | * (white-space) decoration. |
| 110 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 111 | void writeObjectFieldValueSeparator(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 112 | |
| 113 | // // // Array handling |
| 114 | |
| 115 | /** |
| 116 | * Method called when an Array value is to be output, before |
| 117 | * any member/child values are output. |
| 118 | *<p> |
| 119 | * Default handling (without pretty-printing) will output |
| 120 | * the opening bracket. |
| 121 | * Pretty-printer is |
| 122 | * to output a bracket as well, but can surround that |
| 123 | * with other (white-space) decoration. |
| 124 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 125 | void writeStartArray(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 126 | |
| 127 | /** |
| 128 | * Method called after an Array value has been completely output |
| 129 | * (minus closing bracket). |
| 130 | *<p> |
| 131 | * Default handling (without pretty-printing) will output |
| 132 | * the closing bracket. |
| 133 | * Pretty-printer is |
| 134 | * to output a bracket as well, but can surround that |
| 135 | * with other (white-space) decoration. |
| 136 | * |
| 137 | * @param nrOfValues Number of direct members of the array that |
| 138 | * have been output |
| 139 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 140 | void writeEndArray(JsonGenerator gen, int nrOfValues) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 141 | |
| 142 | /** |
| 143 | * Method called after an array value has been completely |
| 144 | * output, and before another value is to be output. |
| 145 | *<p> |
| 146 | * Default handling (without pretty-printing) will output a single |
| 147 | * comma to separate the two. Pretty-printer is |
| 148 | * to output a comma as well, but can surround that with other |
| 149 | * (white-space) decoration. |
| 150 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 151 | void writeArrayValueSeparator(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 152 | |
| 153 | /* |
| 154 | /********************************************************** |
| 155 | /* Then events that by default do not produce any output |
| 156 | /* but that are often overridden to add white space |
| 157 | /* in pretty-printing mode |
| 158 | /********************************************************** |
| 159 | */ |
| 160 | |
| 161 | /** |
| 162 | * Method called after array start marker has been output, |
| 163 | * and right before the first value is to be output. |
| 164 | * It is <b>not</b> called for arrays with no values. |
| 165 | *<p> |
| 166 | * Default handling does not output anything, but pretty-printer |
| 167 | * is free to add any white space decoration. |
| 168 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 169 | void beforeArrayValues(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 170 | |
| 171 | /** |
| 172 | * Method called after object start marker has been output, |
| 173 | * and right before the field name of the first entry is |
| 174 | * to be output. |
| 175 | * It is <b>not</b> called for objects without entries. |
| 176 | *<p> |
| 177 | * Default handling does not output anything, but pretty-printer |
| 178 | * is free to add any white space decoration. |
| 179 | */ |
Tatu Saloranta | 5333247 | 2017-05-23 13:13:17 -0700 | [diff] [blame] | 180 | void beforeObjectEntries(JsonGenerator gen) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 181 | } |
| 182 | |