General utilities used throughout this library.
Classes
ArrayMap<K,V>
Memory-efficient map of keys to values with list-style random-access semantics.
Supports null keys and values. Conceptually, the keys and values are stored in a simpler array in order to minimize memory use and provide for fast access to a key/value at a certain index (for example #getKey(int)). However, traditional mapping operations like #get(Object) and #put(Object, Object) are slower because they need to look up all key/value pairs in the worst case.
Implementation is not thread-safe. For a thread-safe choice instead use an implementation of ConcurrentMap.
ArrayValueMap
Collects the array values of a key/value data object, writing the fields or map values only after all values have been collected.
The typical application for this is when parsing JSON or XML when the value type is known to be an array. It stores the values in a collection during the parsing, and only when the parsing of an object is finished does it convert the collection into an array and stores it.
Use #put(String, Class, Object) when the destination object is a map with string keys
and whose values accept an array of objects. Use #put(Field, Class, Object) when setting
the value of a field using reflection, assuming its type accepts an array of objects. One can
potentially use both put methods for example on an instance of GenericData.
Implementation is not thread-safe. For a thread-safe choice instead use an implementation of ConcurrentMap.
BackOffUtils
Base64 (deprecated)
Deprecated. use com.google.common.io.BaseEncoding#base64
Proxy for handling Base64 encoding/decoding.
ByteArrayStreamingContent (deprecated)
Deprecated. use com.google.common.io.ByteSource
Streaming content whose source is a byte array.
Implementation is not thread-safe.
ByteStreams (deprecated)
Deprecated. use Guava's com.google.common.io.ByteStreams
Provides utility methods for working with byte arrays and I/O streams.
Charsets (deprecated)
Deprecated. use java.nio.charset.StandardCharsets
Contains constant definitions for some standard Charset instances that are guaranteed to be supported by all Java platform implementations.
NOTE: this is a copy of a subset of Guava's com.google.common.base.Charsets. The implementation must match as closely as possible to Guava's implementation.
ClassInfo
Computes class information to determine data key name/value pairs associated with the class.
Implementation is thread-safe.
Collections2 (deprecated)
Deprecated. use Guava's com.google.common.collect.Collections2
Static utility methods pertaining to Collection instances.
Data
Utilities for working with key/value data based on the Key annotation.
DateTime
Immutable representation of a date with an optional time and an optional time zone based on RFC 3339.
Implementation is immutable and therefore thread-safe.
DateTime.SecondsAndNanos
A timestamp represented as the number of seconds and nanoseconds since Epoch.
ExponentialBackOff
Implementation of BackOff that increases the back off period for each retry attempt using a randomization function that grows exponentially.
#nextBackOffMillis() is calculated using the following formula:
randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])
In other words #nextBackOffMillis() will range between the randomization factor percentage below and above the retry interval. For example, using 2 seconds as the base retry interval and 0.5 as the randomization factor, the actual back off period used in the next retry attempt will be between 1 and 3 seconds.
Note: max_interval caps the retry_interval and not the randomized_interval.
If the time elapsed since an ExponentialBackOff instance is created goes past the max_elapsed_time then the method #nextBackOffMillis() starts returning BackOff#STOP. The elapsed time can be reset by calling #reset().
Example: The default retry_interval is .5 seconds, default randomization_factor is 0.5, default multiplier is 1.5 and the default max_interval is 1 minute. For 10 tries the sequence will be (values in seconds) and assuming we go over the max_elapsed_time on the 10th try:
request# retry_interval randomized_interval 1 0.5 [0.25, 0.75] 2 0.75 [0.375, 1.125] 3 1.125 [0.562, 1.687] 4 1.687 [0.8435, 2.53] 5 2.53 [1.265, 3.795] 6 3.795 [1.897, 5.692] 7 5.692 [2.846, 8.538] 8 8.538 [4.269, 12.807] 9 12.807 [6.403, 19.210] 10 19.210 BackOff#STOP
Implementation is not thread-safe.
ExponentialBackOff.Builder
Builder for ExponentialBackOff.
Implementation is not thread-safe.
FieldInfo
Parses field information to determine data key name/value pair associated with the field.
Implementation is thread-safe.
GenericData
Generic data that stores all unknown data key name/value pairs.
Subclasses can declare fields for known data keys using the Key annotation. Each field
can be of any visibility (private, package private, protected, or public) and must not be static.
null unknown data key names are not allowed, but null data values are allowed.
Iteration order of the data keys is based on the sorted (ascending) key names of the declared fields, followed by the iteration order of all of the unknown data key name/value pairs.
Implementation is not thread-safe. For a thread-safe choice instead use an implementation of ConcurrentMap.
IOUtils
Utilities for I/O streams.
Joiner
An object which joins pieces of text (specified as an array, Iterable, varargs or even a Map) with a separator.
NOTE: proxy for the Guava implementation of com.google.common.base.Joiner.
Lists
Static utility methods pertaining to List instances.
NOTE: this is a copy of a subset of Guava's com.google.common.collect.Lists. The implementation must match as closely as possible to Guava's implementation.
LoggingByteArrayOutputStream
Thread-safe byte array output stream that logs what was written to it when the stream is closed.
Use this as a safe way to log a limited amount of content. As content is written to the stream, it is stored as a byte array, up to the maximum number of bytes limit that was set in the constructor. Note that if the maximum limit is set too high, it risks an OutOfMemoryError on low-memory devices. This class also keeps track of the total number of bytes written, regardless of whether they were logged. On #close(), it then logs two records to the specified logger and logging level: the total number of bytes written, and the bounded content logged (assuming charset "UTF-8"). Any control characters are stripped out of the content.
LoggingInputStream
Thread-safe input stream wrapper that forwards all reads to a given input stream, while logging all reads to a LoggingByteArrayOutputStream.
LoggingOutputStream
Thread-safe output stream wrapper that forwards all writes to a given output stream, while logging all writes to a LoggingByteArrayOutputStream.
LoggingStreamingContent
Wraps another streaming content without modifying the content, but also logging content using LoggingOutputStream.
Implementation is not thread-safe.
Maps
Static utility methods pertaining to Map instances.
NOTE: this is a copy of a subset of Guava's com.google.common.collect.Maps. The implementation must match as closely as possible to Guava's implementation.
Objects
Helper functions that can operate on any Object.
Objects.ToStringHelper
Support class for Objects#toStringHelper.
PemReader
Beta
PEM file reader.
Supports reading any PEM stream that contains Base64 encoded content stored inside
"-----BEGIN ...-----" and "-----END ...-----" tags. Each call to #readNextSection() parses the next section in the PEM file. If you need a section of a certain
title use #readNextSection(String), for example readNextSection("PRIVATE KEY").
To ensure that the stream is closed properly, call #close() in a finally block.
As a convenience, use #readFirstSectionAndClose(Reader) or #readFirstSectionAndClose(Reader, String) for the common case of only a single section in a PEM file (or only a single section of a given title).
Limitations:
- Assumes the PEM file section content is not encrypted and cannot handle the case of any headers inside the BEGIN and END tag.
- It also ignores any attributes associated with any PEM file section.
PemReader.Section
Section in the PEM file.
Preconditions
Simple static methods to be called at the start of your own methods to verify correct arguments and state.
NOTE: proxy for the Guava implementation of com.google.common.base.Preconditions.
SecurityUtils
Utilities related to Java security.
Sets
Static utility methods pertaining to Set instances.
NOTE: this is a copy of a subset of Guava's com.google.common.collect.Sets. The implementation must match as closely as possible to Guava's implementation.
SslUtils
SSL utilities.
StringUtils
Utilities for strings.
Strings
Static utility methods pertaining to String instances.
NOTE: proxy for the Guava implementation of com.google.common.base.Strings.
Throwables
Static utility methods pertaining to instances of Throwable.
NOTE: proxy for the Guava implementation of com.google.common.base.Throwables.
Types
Utilities for working with Java types.
Interfaces
BackOff
Back-off policy when retrying an operation.
Clock
Clock which can be used to get the amount of elapsed milliseconds in system time.
The default system implementation can be accessed at #SYSTEM. Alternative implementations may be used for testing.
NanoClock
Nano clock which can be used to measure elapsed time in nanoseconds.
The default system implementation can be accessed at #SYSTEM. Alternative implementations may be used for testing.
ObjectParser
Parses a data source into the specified data type.
Implementations should normally be thread-safe.
Sleeper
Sleeper interface to use for requesting the current thread to sleep as specified in Thread#sleep(long).
The default implementation can be accessed at #DEFAULT. Primarily used for testing.
StreamingContent (deprecated)
Deprecated. use com.google.common.io.ByteSink
Streaming content interface to write bytes to an output stream.
Implementations don't need to be thread-safe.
Enums
GenericData.Flags
Flags that impact behavior of generic data.
Annotation Types
Beta (deprecated)
Deprecated. use com.google.common.annotations.Beta
Use this annotation to indicate that a public API (class, method or field) is beta.
Beta API is subject to incompatible changes or removal in the future. It may also mean that the server features it depends on are potentially subject to breakage at any time.
That API is exempt from any compatibility guarantees made by its containing library. Read carefully the JavaDoc of the API bearing this annotation for better understanding of the risk.
To provide a smoother upgrade path when we make incompatible changes to beta API, whenever possible we try to deprecate the old beta API in the first minor release, and then remove it in the second minor release.
It is generally inadvisable for other non-beta libraries to use beta API from this library. The problem is that other libraries don't have control over the version of this library being used in client applications, and if the wrong version of this library is used, it has the potential to break client applications.
You may use the google-http-client-findbugs plugin to find usages of API bearing this annotation.
Key
Use this annotation to specify that a field is a data key, optionally providing the data key name to use.
If the data key name is not specified, the default is the Java field's name. For example:
public class A {
// uses data key name of "dataKeyNameMatchesFieldName"
@Key
public String dataKeyNameMatchesFieldName;
// uses data key name of "some_other_name"
@Key("some_other_name")
private String dataKeyNameIsOverridden;
// not a data key
private String notADataKey;
}
NullValue
Use this annotation to specify that an enum constant is the "null" data value to use for <xref uid="com.google.api.client.util.Data.
See Value for an example.
Value
Use this annotation to specify that an enum constant is a string data value, optionally providing the string data value to use.
If the string data value is not specified, the default is the Java field's name. For example:
public enum A {
// value is "USE_FIELD_NAME" @Value USE_FIELD_NAME,
// value is "specifiedValue" @Value("specifiedValue") USE_SPECIFIED_VALUE,
// value is null @NullValue NULL_VALUE
// not a value NOT_A_VALUE }