1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc.  All rights reserved.
3// http://code.google.com/p/protobuf/
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions are
7// met:
8//
9//     * Redistributions of source code must retain the above copyright
10// notice, this list of conditions and the following disclaimer.
11//     * Redistributions in binary form must reproduce the above
12// copyright notice, this list of conditions and the following disclaimer
13// in the documentation and/or other materials provided with the
14// distribution.
15//     * Neither the name of Google Inc. nor the names of its
16// contributors may be used to endorse or promote products derived from
17// this software without specific prior written permission.
18//
19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31package com.google.protobuf;
32
33import java.io.UnsupportedEncodingException;
34
35/**
36 * The classes contained within are used internally by the Protocol Buffer
37 * library and generated message implementations. They are public only because
38 * those generated messages do not reside in the {@code protobuf} package.
39 * Others should not use this class directly.
40 *
41 * @author kenton@google.com (Kenton Varda)
42 */
43public class Internal {
44  /**
45   * Helper called by generated code to construct default values for string
46   * fields.
47   * <p>
48   * The protocol compiler does not actually contain a UTF-8 decoder -- it
49   * just pushes UTF-8-encoded text around without touching it.  The one place
50   * where this presents a problem is when generating Java string literals.
51   * Unicode characters in the string literal would normally need to be encoded
52   * using a Unicode escape sequence, which would require decoding them.
53   * To get around this, protoc instead embeds the UTF-8 bytes into the
54   * generated code and leaves it to the runtime library to decode them.
55   * <p>
56   * It gets worse, though.  If protoc just generated a byte array, like:
57   *   new byte[] {0x12, 0x34, 0x56, 0x78}
58   * Java actually generates *code* which allocates an array and then fills
59   * in each value.  This is much less efficient than just embedding the bytes
60   * directly into the bytecode.  To get around this, we need another
61   * work-around.  String literals are embedded directly, so protoc actually
62   * generates a string literal corresponding to the bytes.  The easiest way
63   * to do this is to use the ISO-8859-1 character set, which corresponds to
64   * the first 256 characters of the Unicode range.  Protoc can then use
65   * good old CEscape to generate the string.
66   * <p>
67   * So we have a string literal which represents a set of bytes which
68   * represents another string.  This function -- stringDefaultValue --
69   * converts from the generated string to the string we actually want.  The
70   * generated code calls this automatically.
71   */
72  public static String stringDefaultValue(String bytes) {
73    try {
74      return new String(bytes.getBytes("ISO-8859-1"), "UTF-8");
75    } catch (UnsupportedEncodingException e) {
76      // This should never happen since all JVMs are required to implement
77      // both of the above character sets.
78      throw new IllegalStateException(
79          "Java VM does not support a standard character set.", e);
80    }
81  }
82
83  /**
84   * Helper called by generated code to construct default values for bytes
85   * fields.
86   * <p>
87   * This is a lot like {@link #stringDefaultValue}, but for bytes fields.
88   * In this case we only need the second of the two hacks -- allowing us to
89   * embed raw bytes as a string literal with ISO-8859-1 encoding.
90   */
91  public static ByteString bytesDefaultValue(String bytes) {
92    try {
93      return ByteString.copyFrom(bytes.getBytes("ISO-8859-1"));
94    } catch (UnsupportedEncodingException e) {
95      // This should never happen since all JVMs are required to implement
96      // ISO-8859-1.
97      throw new IllegalStateException(
98          "Java VM does not support a standard character set.", e);
99    }
100  }
101
102  /**
103   * Interface for an enum value or value descriptor, to be used in FieldSet.
104   * The lite library stores enum values directly in FieldSets but the full
105   * library stores EnumValueDescriptors in order to better support reflection.
106   */
107  public interface EnumLite {
108    int getNumber();
109  }
110
111  /**
112   * Interface for an object which maps integers to {@link EnumLite}s.
113   * {@link Descriptors.EnumDescriptor} implements this interface by mapping
114   * numbers to {@link Descriptors.EnumValueDescriptor}s.  Additionally,
115   * every generated enum type has a static method internalGetValueMap() which
116   * returns an implementation of this type that maps numbers to enum values.
117   */
118  public interface EnumLiteMap<T extends EnumLite> {
119    T findValueByNumber(int number);
120  }
121}
122