Skip to content

Commit

Permalink
fix: Add Documentation (#221)
Browse files Browse the repository at this point in the history
* fix: Add javadoc to public classes.

* fix: Reformat.

* fix: Suggested docs changes.

* fix: Fix mvn site issues.
  • Loading branch information
dpcollins-google committed Aug 25, 2020
1 parent f25077d commit 6c430da
Show file tree
Hide file tree
Showing 35 changed files with 237 additions and 31 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,24 @@
import io.grpc.StatusException;
import java.util.Optional;

/** Settings for construction a Pub/Sub Lite AdminClient. */
@AutoValue
public abstract class AdminClientSettings {

// Required parameters.

/**
* The <a href="https://cloud.google.com/pubsub/lite/docs/locations">cloud region</a> to perform
* admin operations for.
*/
abstract CloudRegion region();

// Optional parameters.

/** The retry settings for this client. */
abstract RetrySettings retrySettings();

/** A stub to use to connect. */
abstract Optional<AdminServiceBlockingStub> stub();

public static Builder newBuilder() {
Expand All @@ -43,13 +52,19 @@ public static Builder newBuilder() {
@AutoValue.Builder
public abstract static class Builder {
// Required parameters.

/** The cloud region to perform admin operations for. */
public abstract Builder setRegion(CloudRegion region);

// Optional parameters.

/** The retry settings for this client. */
public abstract Builder setRetrySettings(RetrySettings retrySettings);

/** A stub to use to connect. */
public abstract Builder setStub(AdminServiceBlockingStub stub);

/** Build the settings object. */
public abstract AdminClientSettings build();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,16 @@
import com.google.auto.value.AutoValue;
import java.io.Serializable;

/** A wrapped string representing a Google Cloud region. */
@AutoValue
public abstract class CloudRegion implements Serializable {
private static final long serialVersionUID = 6814654654L;

/** Construct a CloudRegion from a string. */
public static CloudRegion of(String value) {
return new AutoValue_CloudRegion(value);
}

/** The string representing this region. */
public abstract String value();
}
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
import io.grpc.StatusException;
import java.io.Serializable;

/** A representation of a Google Cloud zone. */
@AutoValue
public abstract class CloudZone implements Serializable {
private static final long serialVersionUID = 867184651465L;
Expand All @@ -29,8 +30,10 @@ public static CloudZone of(CloudRegion region, char zoneId) {
return new AutoValue_CloudZone(region, zoneId);
}

// Construct a CloudZone from a valid zone string. `zone` must be formatted as:
// <location>-<direction><number>-<letter>
/**
* Construct a CloudZone from a valid zone string. `zone` must be formatted as:
* &lt;location&gt;-&lt;direction&gt;&lt;number&gt;-&lt;letter&gt;
*/
public static CloudZone parse(String zone) throws StatusException {
String[] splits = zone.split("-", -1);
if (splits.length != 3) {
Expand All @@ -43,10 +46,13 @@ public static CloudZone parse(String zone) throws StatusException {
return of(region, splits[2].charAt(0));
}

/** The region this zone is in. */
public abstract CloudRegion region();

/** The character identifier for this zone in this region. */
public abstract char zoneId();

/** {@inheritDoc} */
@Override
public final String toString() {
return String.format("%s-%c", region().value(), zoneId());
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
import com.google.api.gax.retrying.RetrySettings;
import org.threeten.bp.Duration;

/** Useful general constants for Pub/Sub Lite. */
public class Constants {
public static final RetrySettings DEFAULT_RETRY_SETTINGS =
RetrySettings.newBuilder()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@

package com.google.cloud.pubsublite;

/** Constructs regional endpoints from a CloudRegion. */
public final class Endpoints {
/** Construct a regional endpoint from a CloudRegion. */
public static String regionalEndpoint(CloudRegion region) {
return region.value() + "-pubsublite.googleapis.com";
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
import com.google.common.collect.ImmutableSet;
import io.grpc.Status.Code;

/** Pub/Sub Lite retryable error codes. */
public final class ErrorCodes {
public static final ImmutableSet<Code> RETRYABLE_CODES =
ImmutableSet.of(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,17 @@
import com.google.auto.value.AutoValue;
import java.io.Serializable;

/**
* A string wrapper representing a project and location. Should be structured like:
*
* <p>projects/&lt;project number&gt;/locations/&lt;cloud zone&gt;
*/
@AutoValue
public abstract class LocationPath implements Serializable {
/** The string value of this location path. */
public abstract String value();

/** Construct a LocationPath from its string value. */
public static LocationPath of(String value) {
checkArgument(!value.isEmpty());
return new AutoValue_LocationPath(value);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,24 +22,29 @@
import com.google.auto.value.AutoValue;
import io.grpc.StatusException;

/** Helpers for constructing valid LocationPaths. */
@AutoValue
public abstract class LocationPaths {
abstract ProjectNumber projectNumber();

abstract CloudZone zone();

/** Create a new LocationPath builder. */
public static Builder newBuilder() {
return new AutoValue_LocationPaths.Builder();
}

@AutoValue.Builder
public abstract static class Builder {
/** The project number. */
public abstract Builder setProjectNumber(ProjectNumber number);

/** The Google Cloud zone. */
public abstract Builder setZone(CloudZone zone);

abstract LocationPaths autoBuild();

/** Build a new LocationPath. */
public LocationPath build() {
LocationPaths built = autoBuild();
return LocationPath.of(
Expand All @@ -53,11 +58,13 @@ private static void checkSplits(String[] splits) throws StatusException {
checkArgument(splits[2].equals("locations"));
}

/** Check that the provided LocationPath is valid. */
public static void check(LocationPath path) throws StatusException {
ProjectNumber unusedProjectNumber = getProjectNumber(path);
CloudZone unusedZone = getZone(path);
}

/** Get the ProjectNumber from a LocationPath. */
public static ProjectNumber getProjectNumber(LocationPath path) throws StatusException {
String[] splits = path.value().split("/");
checkSplits(splits);
Expand All @@ -68,6 +75,7 @@ public static ProjectNumber getProjectNumber(LocationPath path) throws StatusExc
}
}

/** Get the CloudZone from a LocationPath. */
public static CloudZone getZone(LocationPath path) throws StatusException {
String[] splits = path.value().split("/");
checkSplits(splits);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,23 +27,30 @@
/** A user message. */
@AutoValue
public abstract class Message {
/** The key for this message. All messages with the same key are routed to the same partition. */
public abstract ByteString key();

/** The data payload for this message. */
public abstract ByteString data();

/** A multimap of attributes for this message. */
public abstract ImmutableListMultimap<String, ByteString> attributes();

/** The user-provided event time for this message. */
public abstract Optional<Timestamp> eventTime();

/** Get a new builder for a message. */
public static Builder builder() {
return new AutoValue_Message.Builder()
.setKey(ByteString.EMPTY)
.setData(ByteString.EMPTY)
.setAttributes(ImmutableListMultimap.of());
}

/** Convert an existing message to a builder. */
public abstract Builder toBuilder();

/** Convert this to a message proto. */
public PubSubMessage toProto() {
PubSubMessage.Builder builder = PubSubMessage.newBuilder();
builder.setKey(key());
Expand All @@ -60,6 +67,7 @@ public PubSubMessage toProto() {
return builder.build();
}

/** Construct a message from a proto. */
public static Message fromProto(PubSubMessage proto) {
Message.Builder builder = Message.builder().setKey(proto.getKey()).setData(proto.getData());
if (proto.hasEventTime()) {
Expand All @@ -77,14 +85,21 @@ public static Message fromProto(PubSubMessage proto) {

@AutoValue.Builder
public abstract static class Builder {
/**
* The key for this message. All messages with the same key are routed to the same partition.
*/
public abstract Builder setKey(ByteString key);

/** The data payload for this message. */
public abstract Builder setData(ByteString data);

/** A multimap of attributes for this message. */
public abstract Builder setAttributes(ImmutableListMultimap<String, ByteString> attributes);

/** The user provided event time for this message. */
public abstract Builder setEventTime(Timestamp eventTime);

/** Build a message. */
public abstract Message build();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,11 @@

import io.grpc.StatusException;

// A MessageTransformer details how to transform a message of one type to another. It is likely that
// either FromT or ToT will be a Message on publish and SequencedMessage on subscribe.
/**
* A MessageTransformer details how to transform a message of one type to another. It is likely that
* either FromT or ToT will be a Message on publish and SequencedMessage on subscribe.
*/
public interface MessageTransformer<FromT, ToT> {
/** Transform one message type to another. */
ToT transform(FromT from) throws StatusException;
}
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,15 @@
/** An offset in the partition. */
@AutoValue
public abstract class Offset implements Comparable<Offset> {
/** Create an offset. */
public static Offset of(long offset) {
return new AutoValue_Offset(offset);
}

/** The long value of this offset. */
public abstract long value();

/** {@inheritDoc} */
@Override
public int compareTo(Offset o) {
return Long.compare(value(), o.value());
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,12 @@
public abstract class Partition implements Serializable {
private static final long serialVersionUID = 7583927435022345L;

/** Create a partition from its long value. */
public static Partition of(long partition) throws StatusException {
checkArgument(partition >= 0, "Partitions are zero indexed.");
return new AutoValue_Partition(partition);
}

/** The long value of this partition. */
public abstract long value();
}
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,11 @@
import io.grpc.StatusException;
import java.util.concurrent.ExecutionException;

/** Utilities for looking up information on partitions. */
public final class PartitionLookupUtils {
private PartitionLookupUtils() {}

/** Look up the number of partitions in a topic. */
public static int numPartitions(TopicPath topic) throws StatusException {
try (AdminClient client =
AdminClient.create(
Expand All @@ -39,6 +41,7 @@ public static int numPartitions(TopicPath topic) throws StatusException {
}
}

/** Look up the number of partitions in a topic using the provided AdminClient. */
public static int numPartitions(TopicPath topic, AdminClient client) throws StatusException {
ApiFuture<Long> partitionCountFuture = client.getTopicPartitionCount(topic);
try {
Expand All @@ -59,6 +62,7 @@ public static int numPartitions(TopicPath topic, AdminClient client) throws Stat
}
}

/** Look up the number of partitions in the topic associated with a subscription. */
public static int numPartitions(SubscriptionPath subscription) throws StatusException {
try (AdminClient client =
AdminClient.create(
Expand All @@ -71,6 +75,10 @@ public static int numPartitions(SubscriptionPath subscription) throws StatusExce
}
}

/**
* Look up the number of partitions in the topic associated with a subscription using the provided
* AdminClient.
*/
public static int numPartitions(SubscriptionPath subscription, AdminClient client)
throws StatusException {
ApiFuture<Subscription> subscriptionFuture = client.getSubscription(subscription);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,17 @@
import com.google.auto.value.AutoValue;
import io.grpc.StatusException;

/**
* A wrapper class for the <a
* href="https://cloud.google.com/resource-manager/docs/creating-managing-projects#before_you_begin">project
* number</a>.
*/
@AutoValue
public abstract class ProjectNumber {
/** The long value of this project number. */
public abstract long value();

/** Construct a ProjectNumber from its long value. */
public static ProjectNumber of(long value) throws StatusException {
checkArgument(value > 0);
return new AutoValue_ProjectNumber(value);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,17 @@
import com.google.auto.value.AutoValue;
import java.io.Serializable;

/**
* A string wrapper representing a project. Should be structured like:
*
* <p>projects/&lt;project number&gt;
*/
@AutoValue
public abstract class ProjectPath implements Serializable {
/** The string value of this project path. */
public abstract String value();

/** Construct a ProjectPath from its string value. */
public static ProjectPath of(String value) {
checkArgument(!value.isEmpty());
return new AutoValue_ProjectPath(value);
Expand Down
Loading

0 comments on commit 6c430da

Please sign in to comment.