src/java/com/google/ipc/invalidation/external/client/SystemResources.java

/*
 * Copyright 2011 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.ipc.invalidation.external.client;

import com.google.ipc.invalidation.external.client.types.Callback;
import com.google.ipc.invalidation.external.client.types.SimplePair;
import com.google.ipc.invalidation.external.client.types.Status;
import com.google.ipc.invalidation.util.BaseLogger;

/**
 * Interfaces for the system resources used by the Ticl. System resources are an abstraction layer
 * over the host operating system that provides the Ticl with the ability to schedule events, send
 * network messages, store data, and perform logging.
 * <p>
 * NOTE: All the resource types and SystemResources are required to be thread-safe.
 *
 */
public interface SystemResources {

  /** Interface specifying the logging functionality provided by {@link SystemResources}. */
  public interface Logger extends BaseLogger, ResourceComponent {}

  /** Interface specifying the scheduling functionality provided by {@link SystemResources}. */
  public interface Scheduler extends ResourceComponent {

    /** Symbolic constant representing no scheduling delay, for readability. */
    static final int NO_DELAY = 0;

    /**
     * Schedules {@code runnable} to be run on scheduler's thread after at least {@code delayMs}
     * milliseconds.
     */
    void schedule(int delayMs, Runnable runnable);

    /** Returns whether the current code is executing on the scheduler's thread. */
    boolean isRunningOnThread();

    /**
     * Returns the current time in milliseconds since *some* epoch (NOT necessarily the UNIX epoch).
     * The only requirement is that this time advance at the rate of real time.
     */
    long getCurrentTimeMs();
  }

  /** Interface specifying the network functionality provided by {@link SystemResources}. */
  public interface NetworkChannel extends ResourceComponent {
    /** Interface implemented by listeners for network events. */
    public interface NetworkListener {
      /** Upcall made when a network message has been received from the data center. */
      // Implementation note: this is currently a serialized ServerToClientMessage protocol buffer.
      // Implementors MAY NOT rely on this fact.
      void onMessageReceived(byte[] message);

      /**
       * Upcall made when the network online status has changed. It will be invoked with
       * a boolean indicating whether the network is connected.
       * <p>
       * This is a best-effort upcall. Note that indicating incorrectly that the network is
       * connected can result in unnecessary calls for {@link #sendMessage}. Incorrect information
       * that the network is disconnected can result in messages not being sent by the client
       * library.
       */
      void onOnlineStatusChange(boolean isOnline);

      /**
       * Upcall made when the network address has changed. Note that the network channel
       * implementation is responsible for determining what constitutes the network address and what
       * it means to have it change.
       * <p>
       * This is a best-effort call; however, failure to invoke it may prevent the client from
       * receiving messages and cause it to behave as though offline until its next heartbeat.
       */
      void onAddressChange();
    }

    /** Sends {@code outgoingMessage} to the data center. */
    // Implementation note: this is currently a serialized ClientToServerMessage protocol buffer.
    // Implementors MAY NOT rely on this fact.
    void sendMessage(byte[] outgoingMessage);

    /**
     * Sets the {@link NetworkListener} to which events will be delivered.
     * <p>
     * REQUIRES: no listener already be registered.
     */
    void setListener(NetworkListener listener);
  }

  /**
   * Interface specifying the storage functionality provided by {@link SystemResources}. Basically,
   * the required functionality is a small subset of the method of a regular hash map.
   */
  public interface Storage extends ResourceComponent {

    /**
     * Attempts to persist {@code value} for the given {@code key}. Invokes {@code done} when
     * finished, passing a value that indicates whether it was successful.
     * <p>
     * Note: If a wrie W1 finishes unsuccessfully and then W2 is issued for the same key and W2
     * finishes successfully, W1 must NOT later overwrite W2.
     * <p>
     * REQUIRES: Neither {@code key} nor {@code value} is null.
     */
    void writeKey(String key, byte[] value, Callback<Status> done);

    /**
     * Reads the value corresponding to {@code key} and calls {@code done} with the result.
     * If it finds the key, passes a success status and the value. Else passes a failure status
     * and a null value.
     */
    void readKey(String key, Callback<SimplePair<Status, byte[]>> done);

    /**
     * Deletes the key, value pair corresponding to {@code key}. If the deletion succeeds, calls
     * {@code done} with true; else calls it with false. A deletion of a key that does not exist
     * is considered to have succeeded.
     */
    void deleteKey(String key, Callback<Boolean> done);

    /**
     * Reads all the keys from the underlying store and then calls {@code keyCallback} with
     * each key that was written earlier and not deleted. When all the keys are done, calls
     * {@code keyCallback} with {@code null}. With each key, the code can indicate a
     * failed status, in which case the iteration stops.
     */
    void readAllKeys(Callback<SimplePair<Status, String>> keyCallback);
  }

  /**
   * Interface for a component of a {@link SystemResources} implementation constructed by calls to
   * set* methods of {@link SystemResourcesBuilder}.
   * <p>
   * The SystemResourcesBuilder allows applications to create a single {@link SystemResources}
   * implementation by composing individual building blocks, each of which implements one of the
   * four required interfaces ({@link Logger}, {@link Storage}, {@link NetworkChannel},
   * {@link Scheduler}).
   * <p>
   * However, each interface implementation may require functionality from another. For example, the
   * network implementation may need to do logging. In order to allow this, we require that the
   * interface implementations also implement {@code ResourceComponent}, which specifies the single
   * method {@link #setSystemResources}. It is guaranteed that this method will be invoked exactly
   * once on each interface implementation and before any other calls are made. Implementations can
   * then save a reference to the provided resources for later use.
   * <p>
   * Note: for the obvious reasons of infinite recursion, implementations should not attempt to
   * access themselves through the provided {@link SystemResources}.
   */
  public interface ResourceComponent {

    /** Supplies a {@link SystemResources} instance to the component. */
    void setSystemResources(SystemResources resources);
  }

  //
  // End of nested interfaces
  //

  /**
   * Starts the resources.
   * <p>
   * REQUIRES: This method is called before the resources are used.
   */
  void start();

  /**
   * Stops the resources. After this point, all the resources will eventually stop doing any work
   * (e.g., scheduling, sending/receiving messages from the network etc). They will eventually
   * convert any further operations to no-ops.
   * <p>
   * REQUIRES: Start has been called.
   */
  void stop();

  /** Returns whether the resources are started. */
  boolean isStarted();

  /**
   * Returns information about the client operating system/platform, e.g., Windows, ChromeOS (for
   * debugging/monitoring purposes).
   */
  String getPlatform();

  /** Returns an object that can be used to do logging. */
  Logger getLogger();

  /** Returns an object that can be used to persist data locally. */
  Storage getStorage();

  /** Returns an object that can be used to send and receive messages. */
  NetworkChannel getNetwork();

  /** Returns an object that can be used by the client library to schedule its internal events. */
  Scheduler getInternalScheduler();

  /** Returns an object that can be used to schedule events for the application. */
  Scheduler getListenerScheduler();
}