geode-core/src/main/java/org/apache/geode/cache/client/ClientCache.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
 * agreements. See the NOTICE file distributed with this work for additional information regarding
 * copyright ownership. The ASF licenses this file to You 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 org.apache.geode.cache.client;

import java.net.InetSocketAddress;
import java.util.Properties;
import java.util.Set;

import org.apache.geode.cache.CacheClosedException;
import org.apache.geode.cache.GemFireCache;
import org.apache.geode.cache.Region;
import org.apache.geode.cache.RegionService;
import org.apache.geode.cache.query.QueryService;

/**
 * A ClientCache instance controls the life cycle of the local singleton cache in a client.
 * <p>
 * A ClientCache is created using {@link ClientCacheFactory#create}. See {@link ClientCacheFactory}
 * for common usage patterns for creating the client cache instance.
 * <p>
 * ClientCache provides access to functionality when a member connects as a client to GemFire
 * servers. It provides the following services:
 * <ul>
 * <li>Access to existing regions (see {@link #getRegion} and {@link #rootRegions}).
 * <li>Creation of regions (see {@link #createClientRegionFactory(ClientRegionShortcut)} and
 * {@link #createClientRegionFactory(String)}).
 * <li>Access the query service (see {@link #getQueryService} and
 * {@link #getLocalQueryService}).</li>
 * <li>Access the GemFire logger (see {@link #getLogger}).</li>
 * <li>Access the GemFire distributed system (see {@link #getDistributedSystem}).</li>
 * <li>Access the GemFire resource manager (see {@link #getResourceManager}).</li>
 * <li>Manages local disk stores for this cache instance (see {@link #createDiskStoreFactory}).</li>
 * <li>Creation of authenticated cache views that support multiple users (see
 * {@link #createAuthenticatedView}).
 * </ul>
 * <p>
 * A ClientCache connects to a server using a {@link Pool}. This pool can be configured in the
 * ClientCacheFactory (by default GemFire tries to create a pool which tries to connect to a server
 * on the localhost on port 40404). This default pool is used by {@link Region}s (created using
 * {@link ClientRegionFactory}) to talk to regions on the server.
 * <p>
 * More pools can be created using {@link PoolManager} or by declaring them in cache.xml.
 *
 * @since GemFire 6.5
 */
public interface ClientCache extends GemFireCache {
  /**
   * Return the QueryService for the named pool. The query operations performed using this
   * QueryService will be executed on the servers that are associated with this pool.
   */
  QueryService getQueryService(String poolName);

  /**
   * Return a QueryService that queries the local state in the client cache. These queries will not
   * be sent to a server.
   */
  QueryService getLocalQueryService();

  /**
   * Terminates this object cache and releases all the resources. Calls {@link Region#close} on each
   * region in the cache. After this cache is closed, any further method call on this cache or any
   * region object will throw {@link CacheClosedException}, unless otherwise noted.
   *
   * @param keepalive whether the server should keep the durable client's queues alive for the
   *        timeout period
   * @throws CacheClosedException if the cache is already closed.
   */
  void close(boolean keepalive);

  /**
   * Create and return a client region factory that is initialized to create a region using the
   * given predefined region attributes.
   *
   * @param shortcut the predefined region attributes to initialize the factory with.
   * @return a factory that will produce a client region.
   */
  <K, V> ClientRegionFactory<K, V> createClientRegionFactory(ClientRegionShortcut shortcut);

  /**
   * Create and return a client region factory that is initialized to create a region using the
   * given named region attributes.
   * <p>
   * Named region attributes are defined in cache.xml by setting the name as the value of the
   * <code>id</code> attribute on a <code>region-attributes</code> element.
   *
   * @param regionAttributesId the named region attributes to initialize the factory with.
   * @throws IllegalStateException if named region attributes has not been defined.
   * @return a factory that will produce a client region.
   */
  <K, V> ClientRegionFactory<K, V> createClientRegionFactory(String regionAttributesId);

  /**
   * Notifies the server that this durable client is ready to receive updates. This method is used
   * by durable clients to notify servers that they are ready to receive updates. As soon as the
   * server receives this message, it will forward updates to this client (if necessary).
   * <p>
   * Durable clients must call this method after they are done creating regions and issuing interest
   * registration requests.If it is called before then events will be lost.Any time a new
   * {@link Pool} is created and regions have been added to it then this method needs to be called
   * again.
   * <p>
   *
   * @throws IllegalStateException if called by a non-durable client
   */
  void readyForEvents();

  /**
   * Creates an authenticated cache view using the given user security properties on the client
   * cache's default pool. Multiple views with different user properties can be created on a single
   * client cache.
   *
   * Requires that {@link ClientCacheFactory#setPoolMultiuserAuthentication(boolean)
   * multiuser-authentication} to be set to true on the default pool.
   *
   * Applications must use this instance to do operations, when multiuser-authentication is set to
   * true.
   *
   * <p>
   * Authenticated cache views are only allows to access {@link ClientRegionShortcut#PROXY proxy}
   * regions. The {@link RegionService#getRegion} method will throw IllegalStateException if an
   * attempt is made to get a region that has local storage.
   *
   * @param userSecurityProperties the security properties of a user.
   * @return the {@link RegionService} instance associated with a user and the given properties.
   * @throws UnsupportedOperationException when invoked with multiuser-authentication as false.
   */
  RegionService createAuthenticatedView(Properties userSecurityProperties);

  /**
   * Creates an authenticated cache view using the given user security properties using the given
   * pool to connect to servers. Requires that
   * {@link PoolFactory#setMultiuserAuthentication(boolean) multiuser-authentication} to be set to
   * true on the given pool.
   * <p>
   * See {@link #createAuthenticatedView(Properties)} for more information on the returned cache
   * view.
   *
   * @param userSecurityProperties the security properties of a user.
   * @param poolName - the pool that the users should be authenticated against.
   * @return the {@link RegionService} instance associated with a user and the given properties.
   */
  RegionService createAuthenticatedView(Properties userSecurityProperties, String poolName);

  /**
   * Returns a set of the servers to which this client is currently connected.
   *
   * @since GemFire 6.6
   */
  Set<InetSocketAddress> getCurrentServers();

  /**
   * Returns the default server pool. If one or more non-default pools were configured, this may
   * return null.
   *
   * @since GemFire 7.0
   * @see org.apache.geode.cache.client.Pool
   */
  Pool getDefaultPool();

}