grpc
/
grpc-java
mirror of https://github.com/grpc/grpc-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document valid characters for AsciiMarshaller

This commit is contained in:
Kun Zhang 2015-09-02 14:56:07 -07:00
parent f8a87eecce
commit 609f31a578
1 changed files with 16 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
core/src/main/java/io/grpc/Metadata.java
View File

@ -68,8 +68,9 @@ public class Metadata {
/** /**
* Simple metadata marshaller that encodes strings as is. * Simple metadata marshaller that encodes strings as is.
* *
* <p>This should be used with ASCII strings that only contain printable characters and space. * <p>This should be used with ASCII strings that only contain the characters listed in the class
* Otherwise the output may be considered invalid and discarded by the transport. * comment of {@link AsciiMarshaller}. Otherwise the output may be considered invalid and
* discarded by the transport, or the call may fail.
*/ */
public static final AsciiMarshaller<String> ASCII_STRING_MARSHALLER = public static final AsciiMarshaller<String> ASCII_STRING_MARSHALLER =
new AsciiMarshaller<String>() { new AsciiMarshaller<String>() {
@ -230,8 +231,9 @@ public class Metadata {
* <p>It produces serialized names and values interleaved. result[i*2] are names, while * <p>It produces serialized names and values interleaved. result[i*2] are names, while
* result[i*2+1] are values. * result[i*2+1] are values.
* *
* <p>Names are ASCII string bytes. If the name ends with "-bin", the value can be raw binary. * <p>Names are ASCII string bytes that contains only the characters listed in the class comment
* Otherwise, the value must be printable ASCII characters or space. * of {@link Key}. If the name ends with {@code "-bin"}, the value can be raw binary. Otherwise,
* the value must contain only characters listed in the class comments of {@link AsciiMarshaller}
* *
* <p>The returned byte arrays <em>must not</em> be modified. * <p>The returned byte arrays <em>must not</em> be modified.
* *
@ -354,12 +356,19 @@ public class Metadata {
/** /**
* Marshaller for metadata values that are serialized into ASCII strings that contain only * Marshaller for metadata values that are serialized into ASCII strings that contain only
* printable characters and space. * following characters:
* <ul>
* <li>Space: {@code 0x20}, but must not be at the beginning or at the end of the value.</li>
* <li>ASCII visible characters ({@code 0x21-0x7E}), but excluding comma ({@code ",", 0x2C}).
* </ul>
* <p>Note this has to be the subset of valid characters in {@code field-content} from RFC 7230
* Section 3.2.
*/ */
public interface AsciiMarshaller<T> { public interface AsciiMarshaller<T> {
/** /**
* Serialize a metadata value to a ASCII string that contains only printable characters and * Serialize a metadata value to a ASCII string that contains only the characters listed in the
* space. * class comment of {@link AsciiMarshaller}. Otherwise the output may be considered invalid and
* discarded by the transport, or the call may fail.
* *
* @param value to serialize * @param value to serialize
* @return serialized version of value, or null if value cannot be transmitted. * @return serialized version of value, or null if value cannot be transmitted.