Package com.google.api.client.util (1.45.0)

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.

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.

Beta
Utilities for BackOff.

Deprecated. use com.google.common.io.BaseEncoding#base64

Proxy for handling Base64 encoding/decoding.

Deprecated. use com.google.common.io.ByteSource

Streaming content whose source is a byte array.

Implementation is not thread-safe.

Deprecated. use Guava's com.google.common.io.ByteStreams

Provides utility methods for working with byte arrays and I/O streams.

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.

Computes class information to determine data key name/value pairs associated with the class.

Implementation is thread-safe.

Deprecated. use Guava's com.google.common.collect.Collections2

Static utility methods pertaining to Collection instances.

Utilities for working with key/value data based on the Key annotation.

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.

A timestamp represented as the number of seconds and nanoseconds since Epoch.

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.

Builder for ExponentialBackOff.

Implementation is not thread-safe.

Parses field information to determine data key name/value pair associated with the field.

Implementation is thread-safe.

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.

Utilities for I/O streams.

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.

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.

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.

Thread-safe input stream wrapper that forwards all reads to a given input stream, while logging all reads to a LoggingByteArrayOutputStream.

Thread-safe output stream wrapper that forwards all writes to a given output stream, while logging all writes to a LoggingByteArrayOutputStream.

Wraps another streaming content without modifying the content, but also logging content using LoggingOutputStream.

Implementation is not thread-safe.

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.

Helper functions that can operate on any Object.

Support class for Objects#toStringHelper.

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.

Section in the PEM file.

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.

Utilities related to Java security.

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.

SSL utilities.

Utilities for strings.

Static utility methods pertaining to String instances.

NOTE: proxy for the Guava implementation of com.google.common.base.Strings.

Static utility methods pertaining to instances of Throwable.

NOTE: proxy for the Guava implementation of com.google.common.base.Throwables.

Utilities for working with Java types.

Back-off policy when retrying an operation.

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.

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.

Parses a data source into the specified data type.

Implementations should normally be thread-safe.

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.

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.

Flags that impact behavior of generic data.

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.

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;
 }
 

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.

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 }