clicache/src/ICacheListener.hpp

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

#pragma once


#include "geode_defs.hpp"
#include "IRegion.hpp"
//#include "Region.hpp"

#include "EntryEvent.hpp"
#include "RegionEvent.hpp"

namespace Apache
{
  namespace Geode
  {
    namespace Client
    {

      /// <summary>
      /// An application plug-in that can be installed on a region.
      /// </summary>
      /// <remarks>
      /// Listeners are change notifications that are invoked
      /// AFTER the change has occured for region update operations on a client.
      /// Listeners also receive notifications when entries in a region are modified.
      /// Multiple events can cause concurrent invocation
      /// of <c>ICacheListener</c> methods.  If event A occurs before event B,
      /// there is no guarantee that their corresponding <c>ICacheListener</c>
      /// method invocations will occur in the same order. Any exceptions thrown by
      /// the listener are caught by Geode and logged. If the exception is due to
      /// listener invocation on the same thread where a region operation has been
      /// performed, then a <c>CacheListenerException</c> is thrown back to
      /// the application. If the exception is for a notification received from
      /// server then that is logged and the notification thread moves on to
      /// receiving other notifications.
      /// <para>
      /// A cache listener is defined in the <see cref="RegionAttributes" />.
      /// </para>
      ///
      /// There are two cases in which listeners are invoked. The first is when a
      /// region modification operation (e.g. put, create, destroy, invalidate)
      /// is performed. For this case it is important to ensure that minimal work is
      /// done in the listener before returning control back to Geode since the
      /// operation will block till the listener has not completed. For example,
      /// a listener implementation may choose to hand off the event to a thread pool
      /// that then processes the event on its thread rather than the listener thread.
      /// The second is when notifications are received from java server as a result
      /// of region register interest calls (<c>Region.RegisterKeys</c> etc),
      /// or invalidate notifications when notify-by-subscription is false on the
      /// server. In this case the methods of <c>ICacheListener</c> are invoked
      /// asynchronously (i.e. does not block the thread that receives notification
      /// messages). Additionally for the latter case of notifications from server,
      /// listener is always invoked whether or not local operation is successful
      /// e.g. if a destroy notification is received and key does not exist in the
      /// region, the listener will still be invoked. This is different from the
      /// first case where listeners are invoked only when the region update
      /// operation succeeds.
      /// </remarks>
      /// <seealso cref="RegionAttributesFactory.SetCacheListener" />
      /// <seealso cref="RegionAttributes.CacheListener" />
      /// <seealso cref="ICacheLoader" />
      /// <seealso cref="ICacheWriter" />
      /// <seealso cref="CacheListenerException" />
      generic<class TKey, class TValue>
      public interface class ICacheListener
      {
        public:

        /// <summary>
        /// Handles the event of a new key being added to a region.
        /// </summary>
        /// <remarks>
        /// The entry did not previously exist in this region in the local cache
        /// (even with a null value).
        /// <para>
        /// This function does not throw any exception.
        /// </para>
        /// </remarks>
        /// <param name="ev">
        /// Denotes the event object associated with the entry creation.
        /// </param>
        /// <seealso cref="Region.Create" />
        /// <seealso cref="Region.Put" />
        /// <seealso cref="Region.Get" />
        void AfterCreate(EntryEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Handles the event of an entry's value being modified in a region.
        /// </summary>
        /// <remarks>
        /// This entry previously existed in this region in the local cache,
        /// but its previous value may have been null.
        /// </remarks>
        /// <param name="ev">
        /// EntryEvent denotes the event object associated with updating the entry.
        /// </param>
        /// <seealso cref="Region.Put" />
        void AfterUpdate(EntryEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Handles the event of an entry's value being invalidated.
        /// </summary>
        /// <param name="ev">
        /// EntryEvent denotes the event object associated with the entry invalidation.
        /// </param>
        void AfterInvalidate(EntryEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Handles the event of an entry being destroyed.
        /// </summary>
        /// <param name="ev">
        /// EntryEvent denotes the event object associated with the entry destruction.
        /// </param>
        /// <seealso cref="Region.Destroy" />
        void AfterDestroy(EntryEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Handles the event of a region being cleared.
        /// </summary>
        void AfterRegionClear(RegionEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Handles the event of a region being invalidated.
        /// </summary>
        /// <remarks>
        /// Events are not invoked for each individual value that is invalidated
        /// as a result of the region being invalidated. Each subregion, however,
        /// gets its own <c>RegionInvalidated</c> event invoked on its listener.
        /// </remarks>
        /// <param name="ev">
        /// RegionEvent denotes the event object associated with the region invalidation.
        /// </param>
        /// <seealso cref="Region.InvalidateRegion" />
        void AfterRegionInvalidate(RegionEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Handles the event of a region being destroyed.
        /// </summary>
        /// <remarks>
        /// Events are not invoked for each individual entry that is destroyed
        /// as a result of the region being destroyed. Each subregion, however,
        /// gets its own <c>AfterRegionDestroyed</c> event invoked on its listener.
        /// </remarks>
        /// <param name="ev">
        /// RegionEvent denotes the event object associated with the region destruction.
        /// </param>
        /// <seealso cref="Region.DestroyRegion" />
        void AfterRegionDestroy(RegionEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Handles the event of a region going live.
        /// </summary>
        /// <remarks>
        /// Each subregion gets its own <c>AfterRegionLive</c> event invoked on its listener.
        /// </remarks>
        /// <param name="ev">
        /// RegionEvent denotes the event object associated with the region going live.
        /// </param>
        /// <seealso cref="Cache.ReadyForEvents" />
        void AfterRegionLive(RegionEvent<TKey, TValue>^ ev);

        /// <summary>
        /// Called when the region containing this callback is destroyed, when
        /// the cache is closed.
        /// </summary>
        /// <remarks>
        /// Implementations should clean up any external resources,
        /// such as database connections. Any runtime exceptions this method
        /// throws will be logged.
        /// </remarks>
        /// <param>
        /// It is possible for this method to be called multiple times on a single
        /// callback instance, so implementations must be tolerant of this.
        /// </param>
        /// <seealso cref="Cache.Close" />
        /// <seealso cref="Region.DestroyRegion" />
        void Close(IRegion<TKey, TValue>^ region);

        ///<summary>
        ///Called when all the endpoints associated with region are down.
        ///This will be called when all the endpoints are down for the first time.
        ///If endpoints come up and again go down it will be called again.
        ///This will also be called when all endpoints are down and region is attached to the pool.
        ///</summary>
        ///<remarks>
        ///</remark>
        ///<param>
        ///region Region^ denotes the assosiated region.
        ///</param>
        void AfterRegionDisconnected(IRegion<TKey, TValue>^ region);
      };
    }  // namespace Client
  }  // namespace Geode
}  // namespace Apache