DatabusV3Client.java

package com.linkedin.databus.client.pub;
/*
 *
 * Copyright 2013 LinkedIn Corp. All rights reserved
 *
 * 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.
 *
*/

import com.linkedin.databus.core.data_model.DatabusSubscription;
import com.linkedin.databus2.core.filter.DbusKeyCompositeFilterConfig;

public interface DatabusV3Client extends DatabusClient
{

  /**
   * Subscribes a single consumer to the on-line update stream / bootstrap for the specified subscriptions
   * On a successful call, a registration object is returned
   *
   * It is possible to specify an id, to be used to identify this registration. If rid is null,
   * a unique id is generated by the library and returned through the DatabusEspressoRegistration
   * object ( can be queried through getId() interface )
   *
   * During a client's lifetime, registrationIds are persistent. i.e., it is possible to stop the
   * consumer, bring it back and associate it with the same registration @see DatabusEspressoRegistration
   *
   * @param listener
   * @param rid
   * @param filterConfig
   * @param subs
   * @return
   * @throws DatabusClientException
   */
  public DatabusV3Registration registerDatabusListener(DatabusV3Consumer consumer,
		  											   RegistrationId rid,
		  											   DbusKeyCompositeFilterConfig filterConfig,
		  											   DatabusSubscription ... subs)
         throws DatabusClientException;

  /**
   * Subscribes a group of consumer to the on-line update stream / bootstrap for the specified subscriptions.
   * The onEvent callbacks will be spread and run in parallel across all consumers
   *
   * The association between a registration and consumer is 1:N
   * (N > 1) is allowed if and only if all of the consumers have the same subscriptions
   *
   * @param listeners
   * @param rid
   * @param filterConfig
   * @param subs : Espresso subscriptions with a URI format as follows:
   *
     *  espresso:[//authority]/dbName/partition[/table]
     *  <ul>
     *     <li><i>authority</i> can be MASTER, SLAVE, ANY; by default is ANY
     *     <li><i>dbName</i> is the espresso DB name
     *     <li><i>partition</i> is the partition number of * for all partitions
     *     <li><i>table</i> is the espresso table name or * for all tables; default is *
     *  </ul>
   * @return DatabusV3Registration object
   * @throws DatabusClientException
   */
  public DatabusV3Registration registerDatabusListener(DatabusV3Consumer[] consumers,
		  									           RegistrationId rid,
		  									           DbusKeyCompositeFilterConfig filterConfig,
		  									           DatabusSubscription ... subs)
         throws DatabusClientException;

  /**
   * A registrationId uniquely identifies a DatabusV3Registration object in a given client.
   *
   * The function below is provided for convenience to retrieve a DatabusEspressoRegistration object
   * given its id. If there does not exist an object with such an id, it returns null
   *
   * @param id
   * @return Return a DatabusRegistration object given its id
   */
  public DatabusV3Registration getRegistration(RegistrationId rid);

  /**
   * This method is used to register a consumer factory with the client in load-balanced mode
   *
   * All the parameters below are required
   * @param clientClusterName Name of the client cluster in Helix to connect
   * @param consumerFactory   A concrete implementation for DbusClusterConsumerFactory
   * @param sourceUris        A comma-separate list of source URIs from which the application wants to consume change events.
   *                          The sources are expected to be in URI format as described in {@link EspressoSubscriptionUriCodec}.
   *
   *  Examples for valid format of sources:
   *  espresso:/MyDB/<wildcard>/<wildcard> [In MyDB on Espresso, all partitions and all tables] (or)
   *  espresso:/MyDB/1/<wildcard> [In MyDB on Espresso, partition 1 and all tables] (or)
   *  espresso:/MyDB/<wildcard>/Table1 [In MyDB on Espresso, all partitions, only Table1] (or)
   *  espresso:/MyDB/<wildcard>/Table1,espresso:/MyDB/<wildcard>/Table2 [In MyDB on Espresso, all partitions, Table1 and Table2]
   *
   *  Non-wildcard partitioned subscriptions are not accepted for this api.
   *  Examples of invalid format of sources:
   *  espresso:/MyDB/0/<wildcard>
   *  espresso:/MyDB/0/table1,espresso:/MyDB/1/Table2
   *
   *  A client cluster can only support one database. Further, the database name must be the same across all registrations for the
   *  client cluster. If different database names are specified, the behavior is undefined.
   *
   * @return DatabusV3Registration A parent registration is returned to the client which may be cached for informational purpose.
   *         Please see {@link DatabusV3Registration} for more information
   */
  public DatabusV3Registration registerCluster(String clientClusterName,
                                               DbusV3ClusterConsumerFactory consumerFactory,
                                               String... sourceUris)
  throws DatabusClientException;

}