/*
 * 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;

/**
 * A user-defined object defined in the {@link RegionAttributes} that is called synchronously before
 * a region or entry in the cache is modified. The typical use for a <code>CacheWriter</code> is to
 * update a database. Application writers should implement these methods to execute
 * application-specific behavior before the cache is modified.
 *
 * <p>
 * Before the region is updated via a put, create, or destroy operation, GemFire will call a
 * <code>CacheWriter</code> that is installed anywhere in any participating cache for that region,
 * preferring a local <code>CacheWriter</code> if there is one. Usually there will be only one
 * <code>CacheWriter</code> in the distributed system. If there are multiple
 * <code>CacheWriter</code>s available in the distributed system, the GemFire implementation always
 * prefers one that is stored locally, or else picks one arbitrarily; in any case only one
 * <code>CacheWriter</code> will be invoked.
 *
 * <p>
 * The <code>CacheWriter</code> is capable of aborting the update to the cache by throwing a
 * <code>CacheWriterException</code>. This exception or any runtime exception thrown by the
 * <code>CacheWriter</code> will abort the operation and the exception will be propagated to the
 * initiator of the operation, regardless of whether the initiator is in the same VM as the
 * <code>CacheWriter</code>.
 *
 * <p>
 * WARNING: To avoid risk of deadlock, do not invoke CacheFactory.getAnyInstance() from within any
 * callback methods. Instead use EntryEvent.getRegion().getCache() or
 * RegionEvent.getRegion().getCache().
 *
 * @see AttributesFactory#setCacheWriter
 * @see RegionAttributes#getCacheWriter
 * @see AttributesMutator#setCacheWriter
 * @since GemFire 3.0
 */
public interface CacheWriter<K, V> extends CacheCallback {

  /**
   * Called before an entry is updated. The entry update is initiated by a <code>put</code> or a
   * <code>get</code> that causes the loader to update an existing entry. The entry previously
   * existed in the cache where the operation was initiated, although the old value may have been
   * null. The entry being updated may or may not exist in the local cache where the CacheWriter is
   * installed.
   *
   * @param event an EntryEvent that provides information about the operation in progress
   * @throws CacheWriterException if thrown will abort the operation in progress, and the exception
   *         will be propagated back to caller that initiated the operation
   * @see Region#put(Object, Object)
   * @see Region#get(Object)
   */
  void beforeUpdate(EntryEvent<K, V> event) throws CacheWriterException;

  /**
   * Called before an entry is created. Entry creation is initiated by a <code>create</code>, a
   * <code>put</code>, or a <code>get</code>. The <code>CacheWriter</code> can determine whether
   * this value comes from a <code>get</code> or not by evaluating the
   * {@link CacheEvent#getOperation() Operation}'s {@link Operation#isLoad()} method. The entry
   * being created may already exist in the local cache where this <code>CacheWriter</code> is
   * installed, but it does not yet exist in the cache where the operation was initiated.
   *
   * @param event an EntryEvent that provides information about the operation in progress
   * @throws CacheWriterException if thrown will abort the operation in progress, and the exception
   *         will be propagated back to caller that initiated the operation
   * @see Region#create(Object, Object)
   * @see Region#put(Object, Object)
   * @see Region#get(Object)
   */
  void beforeCreate(EntryEvent<K, V> event) throws CacheWriterException;

  /**
   * Called before an entry is destroyed. The entry being destroyed may or may not exist in the
   * local cache where the CacheWriter is installed. This method is <em>not</em> called as a result
   * of expiration or {@link Region#localDestroy(Object)}.
   *
   * @param event an EntryEvent that provides information about the operation in progress
   * @throws CacheWriterException if thrown will abort the operation in progress, and the exception
   *         will be propagated back to caller that initiated the operation
   *
   * @see Region#destroy(Object)
   */
  void beforeDestroy(EntryEvent<K, V> event) throws CacheWriterException;

  /**
   * Called before a region is destroyed. The <code>CacheWriter</code> will not additionally be
   * called for each entry that is destroyed in the region as a result of a region destroy. If the
   * region's subregions have <code>CacheWriter</code>s installed, then they will be called for the
   * cascading subregion destroys. This method is <em>not</em> called as a result of
   * {@link Region#close}, {@link Cache#close}, or {@link Region#localDestroyRegion()}. However, the
   * {@link Region#close} method is invoked regardless of whether a region is destroyed locally. A
   * non-local region destroy results in an invocation of {@link #beforeRegionDestroy} followed by
   * an invocation of {@link Region#close}.
   * <p>
   * WARNING: This method should not destroy or create any regions itself or a deadlock will occur.
   *
   * @param event a RegionEvent that provides information about the operation
   *
   * @throws CacheWriterException if thrown, will abort the operation in progress, and the exception
   *         will be propagated back to the caller that initiated the operation
   *
   * @see Region#destroyRegion()
   */
  void beforeRegionDestroy(RegionEvent<K, V> event) throws CacheWriterException;

  /**
   * Called before a region is cleared. The <code>CacheWriter</code> will not additionally be called
   * for each entry that is cleared in the region as a result of a region clear.
   *
   * <p>
   * WARNING: This method should not clear/destroy any regions
   *
   *
   * @param event a RegionEvent that provides information about the operation
   *
   * @throws CacheWriterException if thrown, will abort the operation in progress, and the exception
   *         will be propagated back to the caller that initiated the operation
   *
   * @see Region#clear
   */
  void beforeRegionClear(RegionEvent<K, V> event) throws CacheWriterException;
}