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