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 | |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 8 | import java.io.IOException; |
| 9 | import java.io.OutputStream; |
| 10 | import java.nio.ByteBuffer; |
| 11 | |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 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. |
Tatu Saloranta | 066463a | 2013-09-22 19:57:25 -0700 | [diff] [blame] | 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). |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 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 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 30 | String getValue(); |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 31 | |
| 32 | /** |
| 33 | * Returns length of the (unquoted) String as characters. |
| 34 | * Functionally equvalent to: |
| 35 | *<pre> |
| 36 | * getValue().length(); |
| 37 | *</pre> |
| 38 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 39 | int charLength(); |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 40 | |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 41 | /* |
| 42 | /********************************************************** |
| 43 | /* Accessors for byte sequences |
| 44 | /********************************************************** |
| 45 | */ |
| 46 | |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 47 | /** |
Tatu Saloranta | 066463a | 2013-09-22 19:57:25 -0700 | [diff] [blame] | 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. |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 50 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 51 | char[] asQuotedChars(); |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 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 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 60 | byte[] asUnquotedUTF8(); |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 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 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 69 | byte[] asQuotedUTF8(); |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 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 |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 88 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 89 | int appendQuotedUTF8(byte[] buffer, int offset); |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 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 |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 101 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 102 | int appendQuoted(char[] buffer, int offset); |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 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 |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 114 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 115 | int appendUnquotedUTF8(byte[] buffer, int offset); |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 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 |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 128 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 129 | int appendUnquoted(char[] buffer, int offset); |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 130 | |
| 131 | /* |
| 132 | /********************************************************** |
| 133 | /* Helper methods for writing out byte sequences |
| 134 | /********************************************************** |
| 135 | */ |
| 136 | |
| 137 | /** |
| 138 | * @return Number of bytes written |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 139 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 140 | int writeQuotedUTF8(OutputStream out) throws IOException; |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 141 | |
| 142 | /** |
| 143 | * @return Number of bytes written |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 144 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 145 | int writeUnquotedUTF8(OutputStream out) throws IOException; |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 146 | |
| 147 | /** |
| 148 | * @return Number of bytes put, if successful, otherwise -1 |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 149 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 150 | int putQuotedUTF8(ByteBuffer buffer) throws IOException; |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 151 | |
| 152 | /** |
| 153 | * @return Number of bytes put, if successful, otherwise -1 |
Tatu Saloranta | 0ccc4c9 | 2012-01-17 22:13:16 -0800 | [diff] [blame] | 154 | */ |
Francis Galiegue | 4d5def1 | 2012-09-29 12:26:42 +0200 | [diff] [blame] | 155 | int putUnquotedUTF8(ByteBuffer out) throws IOException; |
Tatu Saloranta | f15531c | 2011-12-22 23:00:40 -0800 | [diff] [blame] | 156 | } |