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

Common utilities for Google APIs in Java

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Google API Common

Name: tessl/maven-com-google-api--api-common
Author: tessl

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

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:maven/com.google.api/api-common@2.50.x
Publish Source: CLI
Badge