1 /* Jackson JSON-processor.
2  *
3  * Copyright (c) 2007- Tatu Saloranta, tatu.saloranta@iki.fi
4  */
5 
6 package com.fasterxml.jackson.core;
7 
8 import java.io.IOException;
9 import java.io.OutputStream;
10 import java.nio.ByteBuffer;
11 
12 /**
13  * Interface that defines how Jackson package can interact with efficient
14  * pre-serialized or lazily-serialized and reused String representations.
15  * Typically implementations store possible serialized version(s) so that
16  * serialization of String can be done more efficiently, especially when
17  * used multiple times.
18  *<p>
19  * Note that "quoted" in methods means quoting of 'special' characters using
20  * JSON backlash notation (and not use of actual double quotes).
21  *
22  * @see com.fasterxml.jackson.core.io.SerializedString
23  */
24 public interface SerializableString
25 {
26     /**
27      * Returns unquoted String that this object represents (and offers
28      * serialized forms for)
29      */
getValue()30     String getValue();
31 
32     /**
33      * Returns length of the (unquoted) String as characters.
34      * Functionally equivalent to:
35      *<pre>
36      *   getValue().length();
37      *</pre>
38      */
charLength()39     int charLength();
40 
41     /*
42     /**********************************************************
43     /* Accessors for byte sequences
44     /**********************************************************
45      */
46 
47     /**
48      * Returns JSON quoted form of the String, as character array.
49      * Result can be embedded as-is in textual JSON as property name or JSON String.
50      */
asQuotedChars()51     char[] asQuotedChars();
52 
53     /**
54      * Returns UTF-8 encoded version of unquoted String.
55      * Functionally equivalent to (but more efficient than):
56      *<pre>
57      * getValue().getBytes("UTF-8");
58      *</pre>
59      */
asUnquotedUTF8()60     byte[] asUnquotedUTF8();
61 
62     /**
63      * Returns UTF-8 encoded version of JSON-quoted String.
64      * Functionally equivalent to (but more efficient than):
65      *<pre>
66      * new String(asQuotedChars()).getBytes("UTF-8");
67      *</pre>
68      */
asQuotedUTF8()69     byte[] asQuotedUTF8();
70 
71     /*
72     /**********************************************************
73     /* Helper methods for appending byte/char sequences
74     /**********************************************************
75      */
76 
77     /**
78      * Method that will append quoted UTF-8 bytes of this String into given
79      * buffer, if there is enough room; if not, returns -1.
80      * Functionally equivalent to:
81      *<pre>
82      *  byte[] bytes = str.asQuotedUTF8();
83      *  System.arraycopy(bytes, 0, buffer, offset, bytes.length);
84      *  return bytes.length;
85      *</pre>
86      *
87      * @return Number of bytes appended, if successful, otherwise -1
88      */
appendQuotedUTF8(byte[] buffer, int offset)89     int appendQuotedUTF8(byte[] buffer, int offset);
90 
91     /**
92      * Method that will append quoted characters of this String into given
93      * buffer. Functionally equivalent to:
94      *<pre>
95      *  char[] ch = str.asQuotedChars();
96      *  System.arraycopy(ch, 0, buffer, offset, ch.length);
97      *  return ch.length;
98      *</pre>
99      *
100      * @return Number of characters appended, if successful, otherwise -1
101      */
appendQuoted(char[] buffer, int offset)102     int appendQuoted(char[] buffer, int offset);
103 
104     /**
105      * Method that will append unquoted ('raw') UTF-8 bytes of this String into given
106      * buffer. Functionally equivalent to:
107      *<pre>
108      *  byte[] bytes = str.asUnquotedUTF8();
109      *  System.arraycopy(bytes, 0, buffer, offset, bytes.length);
110      *  return bytes.length;
111      *</pre>
112      *
113      * @return Number of bytes appended, if successful, otherwise -1
114      */
appendUnquotedUTF8(byte[] buffer, int offset)115     int appendUnquotedUTF8(byte[] buffer, int offset);
116 
117 
118     /**
119      * Method that will append unquoted characters of this String into given
120      * buffer. Functionally equivalent to:
121      *<pre>
122      *  char[] ch = str.getValue().toCharArray();
123      *  System.arraycopy(bytes, 0, buffer, offset, ch.length);
124      *  return ch.length;
125      *</pre>
126      *
127      * @return Number of characters appended, if successful, otherwise -1
128      */
appendUnquoted(char[] buffer, int offset)129     int appendUnquoted(char[] buffer, int offset);
130 
131     /*
132     /**********************************************************
133     /* Helper methods for writing out byte sequences
134     /**********************************************************
135      */
136 
137     /**
138      * @return Number of bytes written
139      */
writeQuotedUTF8(OutputStream out)140     int writeQuotedUTF8(OutputStream out) throws IOException;
141 
142     /**
143      * @return Number of bytes written
144      */
writeUnquotedUTF8(OutputStream out)145     int writeUnquotedUTF8(OutputStream out) throws IOException;
146 
147     /**
148      * @return Number of bytes put, if successful, otherwise -1
149      */
putQuotedUTF8(ByteBuffer buffer)150     int putQuotedUTF8(ByteBuffer buffer) throws IOException;
151 
152     /**
153      * @return Number of bytes put, if successful, otherwise -1
154      */
putUnquotedUTF8(ByteBuffer out)155     int putUnquotedUTF8(ByteBuffer out) throws IOException;
156 }
157