or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-api.mdindex.mdpath-template.mdresource-names.md
tile.json

tessl/maven-com-google-api--api-common

Common utilities for Google APIs in Java

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.google.api/api-common@2.50.x

To install, run

npx @tessl/cli install tessl/maven-com-google-api--api-common@2.50.0

index.mddocs/

Google API Common

Google API Common provides foundational types and utilities for building robust Google API client applications in Java. It serves as a core library that enables developers to work with asynchronous operations, service lifecycle management, path templates, and resource name handling across the entire Google Cloud Java ecosystem.

Package Information

  • Package Name: api-common
  • Package Type: maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>com.google.api</groupId>
  <artifactId>api-common</artifactId>
  <version>2.50.0</version>
</dependency>

Core Imports

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutures;
import com.google.api.core.SettableApiFuture;
import com.google.api.pathtemplate.PathTemplate;
import com.google.api.resourcenames.ResourceName;

Basic Usage

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutures;
import com.google.api.core.SettableApiFuture;
import com.google.api.pathtemplate.PathTemplate;
import com.google.common.util.concurrent.MoreExecutors;

// Create and manipulate futures
SettableApiFuture<String> future = SettableApiFuture.create();
future.set("Hello World");

// Transform future results
ApiFuture<Integer> lengthFuture = ApiFutures.transform(
    future, 
    String::length, 
    MoreExecutors.directExecutor()
);

// Work with path templates
PathTemplate template = PathTemplate.create("projects/{project}/topics/{topic}");
String path = template.instantiate("my-project", "my-topic");
Map<String, String> vars = template.match("projects/my-project/topics/my-topic");

Architecture

Google API Common is built around several key components:

  • Async Operations: ApiFuture and ApiFutures utilities provide a consistent async programming model similar to Guava's ListenableFuture
  • Service Lifecycle: ApiService interface and AbstractApiService base class for managing service startup/shutdown
  • Path Templates: PathTemplate class for parsing and generating URLs with variable substitution
  • Resource Names: ResourceName interface and implementations for type-safe resource identifier handling
  • API Stability: Annotation system (@BetaApi, @InternalApi) for marking API stability levels
  • Clock Abstraction: ApiClock interface for testable time operations

Capabilities

Asynchronous Operations

Core async programming utilities with futures, callbacks, and transformation operations. Essential for non-blocking API operations and result composition.

interface ApiFuture<V> extends Future<V> {
    void addListener(Runnable listener, Executor executor);
}

class ApiFutures {
    static <V> void addCallback(
        ApiFuture<V> future, 
        ApiFutureCallback<? super V> callback, 
        Executor executor
    );
    static <V> ApiFuture<V> immediateFuture(V value);
    static <I, O> ApiFuture<O> transform(
        ApiFuture<? extends I> input, 
        ApiFunction<? super I, ? extends O> function, 
        Executor executor
    );
}

class SettableApiFuture<V> implements ApiFuture<V> {
    static <V> SettableApiFuture<V> create();
    boolean set(V value);
    boolean setException(Throwable throwable);
}

Core API

Path Template Processing

URL path template parsing, variable extraction, and path generation for Google API resource patterns. Critical for building REST API clients.

class PathTemplate {
    static PathTemplate create(String template);
    boolean matches(String path);
    Map<String, String> match(String path);
    String instantiate(Map<String, String> values);
    Set<String> vars();
}

class TemplatedResourceName implements Map<String, String> {
    static TemplatedResourceName create(PathTemplate template, String path);
    PathTemplate template();
    TemplatedResourceName parentName();
}

Path Templates

Resource Name Handling

Type-safe resource identifier management with support for different resource name formats and factory patterns.

interface ResourceName {
    Map<String, String> getFieldValuesMap();
    String getFieldValue(String fieldName);
}

class UntypedResourceName implements ResourceName {
    static UntypedResourceName parse(String formattedString);
    static boolean isParsableFrom(String formattedString);
}

interface ResourceNameFactory<T extends ResourceName> {
    T parse(String formattedString);
}

Resource Names

Service Lifecycle Management

Managed service lifecycle with startup, shutdown, and state monitoring capabilities for long-running services.

interface ApiService {
    ApiService startAsync();
    ApiService stopAsync();
    void awaitRunning();
    boolean isRunning();
    State state();
    void addListener(Listener listener, Executor executor);
    
    enum State {
        NEW, STARTING, RUNNING, STOPPING, TERMINATED, FAILED
    }
}

abstract class AbstractApiService implements ApiService {
    protected abstract void doStart();
    protected abstract void doStop();
    protected final void notifyStarted();
    protected final void notifyStopped();
}

Core API

Types

Core Functional Interfaces

@FunctionalInterface
interface ApiFunction<F, T> {
    T apply(F input);
}

@FunctionalInterface  
interface ApiAsyncFunction<I, O> {
    ApiFuture<O> apply(I input) throws Exception;
}

interface ApiFutureCallback<V> {
    void onFailure(Throwable t);
    void onSuccess(V result);
}

Clock Abstractions

interface ApiClock {
    long nanoTime();
    long millisTime();
}

class NanoClock implements ApiClock {
    static ApiClock getDefaultClock();
}

class CurrentMillisClock implements ApiClock {
    static ApiClock getDefaultClock();
}

API Stability Annotations

@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})
@interface BetaApi {
    String value() default "";
}

@BetaApi
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})  
@interface InternalApi {
    String value() default "";
}

@BetaApi
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})
@interface ObsoleteApi {
    String value();
}

@BetaApi
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})
@interface InternalExtensionOnly {
    String value() default "";
}