/*
 * 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.management.internal;

import javax.management.Notification;
import javax.management.ObjectName;

import org.apache.geode.distributed.internal.MembershipListener;

/**
 * 
 * A listener to handle MBean proxy related events.
 * 
 * Any custom ProxyListener should implement this interface. For the time being its not exposed to
 * the user. But is being kept as an extension point for future releases if we decide to support
 * custom ProxyListener.
 * 
 * TODO Along side we need to make FederationCompoent public as well.
 * 
 * A simple usage of a ProxyListener could be custom aggregator of Statistics exposed by MBeans.
 * 
 * 
 * ManagementService service = ManagementService .getManagementService(cache);
 * 
 * ProxyListener listener = new MyListener(); //implements ProxyListener.
 * service.addProxyListener(listener)
 * 
 * 
 * Adding an ProxyListener in a non Manager node wont be useful as it wont get any proxy related
 * callbacks
 * 
 * 
 */
public interface ProxyListener extends MembershipListener {

  /**
   * 
   * When a new proxy is added to the Manager this call back is invoked. User can decide what to do
   * with the event. It can take some action or ignore the event.
   * 
   * @param objectName name of the proxy object
   * @param interfaceClass interface class of the proxy object.
   * @param proxyObject actual reference of the proxy. This proxy object can be cast to the input
   *        interface class type.
   * @param newVal new value for the proxy
   * 
   */
  void afterCreateProxy(ObjectName objectName, Class interfaceClass, Object proxyObject,
      FederationComponent newVal);

  /**
   * 
   * When a proxy is removed from the Manager this call back is invoked. User can decide what to do
   * with the event. It can take some action or ignore the event.
   * 
   * @param objectName name of the proxy object
   * @param interfaceClass interface class of the proxy object.
   * @param proxyObject actual reference of the proxy.
   * @param oldVal old value for the proxy
   */
  void afterRemoveProxy(ObjectName objectName, Class interfaceClass, Object proxyObject,
      FederationComponent oldVal);

  /**
   * When a proxy is updated in Manager this call back is invoked. User can decide what to do with
   * the event. It can take some action or ignore the event.
   * 
   * @param objectName name of the proxy object
   * @param interfaceClass interface class of the proxy object.
   * @param proxyObject actual reference of the proxy.
   * @param newVal new value for the proxy
   * @param oldVal old value for the proxy
   */
  void afterUpdateProxy(ObjectName objectName, Class interfaceClass, Object proxyObject,
      FederationComponent newVal, FederationComponent oldVal);

  /**
   * User can implement this method to handle all notifications generated by the System.
   * 
   * @param notification
   */
  public void handleNotification(Notification notification);

  /**
   * This is a very special method, Only to be invoked from MonitoringRegionCacheListener. The need
   * for this interface arises as some time a create op is not meant to create proxies or aggregate.
   * But only to feed data to existing proxies.
   * 
   * e.g. When manager starts and not a single ManagementTask cycle has been run. This will result
   * in lost updates. To capture all updates we can feed the newly created data to existing
   * aggregate.
   * 
   * @param objectName name of the proxy object
   * @param interfaceClass interface class of the proxy object.
   * @param proxyObject actual reference of the proxy. This proxy object can be cast to the input
   *        interface class type.
   * @param newVal new value for the proxy
   */
  public void afterPseudoCreateProxy(ObjectName objectName, Class interfaceClass,
      Object proxyObject, FederationComponent newVal);

}