/*
      Copyright 2007 Ramon Servadei
   
      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.
   */
  package fulmine.model.component;
  
  import static fulmine.util.Utils.EMPTY_STRING;
  import static fulmine.util.Utils.logException;
  import static fulmine.util.Utils.safeToString;
  import static fulmine.util.Utils.string;
  
  import java.util.Collections;
  import java.util.List;
  
  import fulmine.AbstractLifeCycle;
  import fulmine.Addressable;
  import fulmine.IAddressable;
  import fulmine.IDomain;
  import fulmine.IType;
  import fulmine.context.IFrameworkContext;
  import fulmine.event.IEvent;
  import fulmine.event.IEventFrameExecution;
  import fulmine.event.IEventSource;
  import fulmine.event.listener.IEventListener;
  import fulmine.event.listener.IPriorityEventListener;
  import fulmine.event.system.ISystemEvent;
  import fulmine.event.system.ISystemEventListener;
  import fulmine.protocol.wire.IWireIdentity;
  import fulmine.protocol.wire.IWireState;
  import fulmine.protocol.wire.operation.IOperationScope;
  import fulmine.util.array.ArrayUtils;
  import fulmine.util.collection.ReferenceCountingList;
  import fulmine.util.log.AsyncLog;
  
  /**
   * A base component class that implements many common functions. Each component
   * has an identity that is provided during construction. A component is not
   * explicitly related with a {@link IFrameworkContext context}.
   * <p>
   * The abstract component implements the {@link IAddressable} interface. This is
   * an implementation detail and provides the context with the unique identity of
   * this component as an entity.
   * <p>
   * The {@link #addListener(IEventListener)} and
   * {@link #removeListener(IEventListener)} methods use copy-on-write for the
   * collection of listeners.
   * 
   * @author Ramon Servadei
   */
  public abstract class AbstractComponent extends AbstractLifeCycle implements
      IComponent, Cloneable
  {
      private final static AsyncLog LOG = new AsyncLog(AbstractComponent.class);
  
      /** The identity for this */
      private final IAddressable id;
  
      /** The event source group id */
      private final byte eventGroupId;
  
      /** flag to identify if this component is a clone: 0=original, 1=clone */
      private volatile byte isClone;
  
      /** Holds the frame that caused this component to change. */
      private IEventFrameExecution drivingFrame;
  
      /** The frame in which the change for this component occurs. */
      private IEventFrameExecution currentFrame;
  
      /**
       * The listeners registered against this source. Uses the <a
       * href="http://www.ibm.com/developerworks/java/library/j-jtp06197.html"
       * >'cheap read-write lock'</a>
       */
      private volatile List<IEventListener> listeners;
  
      /**
       * The source of events generated by this component; effectively the
       * component itself is the source. If this is a cloned component, the source
       * is the <i>original</i> instance.
       */
      private IEventSource source = this;
  
      /**
       * Construct the component with an identity and type. This assigns a 0 event
       * group id
       * 
       * @param identity
      *            the identity of the component
      * @param type
      *            the type of the component
      * @param domain
      *            the domain of the component
      */
     protected AbstractComponent(String identity, IType type, IDomain domain)
     {
         // by default, just use the 0'th processor
         this(identity, type, domain, (byte) 0);
     }
 
     /**
      * Construct the component with an identity, type and event group id.
      * 
      * @param identity
      *            the identity of the component
      * @param type
      *            the type of the component
      * @param domain
      *            the domain of the component
      * @param eventGroupId
      *            the event group id
      */
     protected AbstractComponent(String identity, IType type, IDomain domain,
         byte eventGroupId)
     {
         super();
         this.id = new Addressable(identity, type, domain);
         /*
          * Because regular expressions are used for subscription handling, we
          * must prevent '**' in the identity.
          */
         if (identity.indexOf("**") > -1)
         {
             throw new RuntimeException(
                 "Containers cannot have the following characters '**', attempted identity "
                     + identity + " for " + type + ", " + domain);
         }
         this.eventGroupId = eventGroupId;
     }
 
     public final byte getEventSourceGroupId()
     {
         return this.eventGroupId;
     }
 
     public final String getIdentity()
     {
         return this.getAddressable().getIdentity();
     }
 
     public final IType getType()
     {
         return this.getAddressable().getType();
     }
 
     public final IDomain getDomain()
     {
         return this.getAddressable().getDomain();
     }
 
     public final String getAddress()
     {
         return this.getAddressable().getAddress();
     }
 
     public final IEventSource getSource()
     {
         return this.source;
     }
 
     public final IEventFrameExecution getDrivingFrame()
     {
         return this.drivingFrame;
     }
 
     public final IEventFrameExecution getFrame()
     {
         return this.currentFrame;
     }
 
     /**
      * Set the event frame identifier for this cloneable component. This method
      * is useful to set the frame for an event so that it matches up with the
      * event frame of an event that generated this event. This allows an
      * {@link IEventListener} to process these events as a single work unit even
      * though they are generated in separate frames.
      * 
      * @param frame
      *            the event frame to associate this {@link IEvent} with.
      */
     public final void setFrame(IEventFrameExecution frame)
     {
         this.currentFrame = frame;
     }
 
     /**
      * Set the driving frame that caused the change in this component
      * 
      * @param drivingFrame
      *            the driving frame
      */
     protected final void setDrivingFrame(IEventFrameExecution drivingFrame)
     {
         this.drivingFrame = drivingFrame;
     }
 
     public final void readState(IOperationScope scope, byte[] dataBuffer,
         int start, int numberOfBytes)
     {
         boolean processed = false;
         try
         {
             if (scope.include(this))
             {
                 processed =
                     doReadState(scope, dataBuffer, start, numberOfBytes);
                 scope.exiting(this, processed);
             }
         }
         catch (Exception e)
         {
             scope.exception(this, e);
         }
     }
 
     public final void writeState(IOperationScope scope, IWireIdentity wireId,
         byte[][] headerBuffer, int[] headerBufferPosition, byte[][] dataBuffer,
         int[] dataBufferPosition, boolean completeState)
     {
         boolean processed = false;
         try
         {
             if (scope.include(this))
             {
                 processed =
                     doWriteState(scope, wireId, headerBuffer,
                         headerBufferPosition, dataBuffer, dataBufferPosition,
                         completeState);
                 scope.exiting(this, processed);
             }
         }
         catch (Exception e)
         {
             scope.exception(this, e);
         }
     }
 
     /**
      * A synchronous notification implementation
      */
     public void addEvent(IEvent event)
     {
         final List<IEventListener> listeners = getListeners();
         for (IEventListener eventListener : listeners)
         {
             eventListener.update(event);
         }
     }
 
     public final boolean addListener(IEventListener listener)
     {
         if (this instanceof ISystemEvent
             && !(listener instanceof ISystemEventListener))
         {
             throw new IllegalArgumentException(this + " can only have "
                 + ISystemEventListener.class.getSimpleName()
                 + " instances added as listeners.");
         }
         boolean added = false;
         List<IEventListener> copy = null;
         // copy-on-write and ensure this is an atomic unit of work
         synchronized (this)
         {
             if (this.listeners == null)
             {
                 copy = new ReferenceCountingList<IEventListener>(0);
             }
             else
             {
                 copy =
                     new ReferenceCountingList<IEventListener>(this.listeners);
             }
             if (listener instanceof IPriorityEventListener)
             {
                 added = !copy.contains(listener);
                 copy.add(0, listener);
             }
             else
             {
                 added = copy.add(listener);
             }
             this.listeners = copy;
             if (added)
             {
                 doPostAddListener(listener);
             }
         }
         if (added)
         {
             try
             {
                 listener.addedAsListenerFor(this);
             }
             catch (Exception e)
             {
                 logException(getLog(), this, e);
             }
             if (getLog().isDebugEnabled())
             {
                 getLog().debug(
                     "Added listener " + safeToString(listener) + " to source "
                         + createIdentityString());
             }
         }
         return added;
     }
 
     public final List<IEventListener> getListeners()
     {
         final List<IEventListener> local = this.listeners;
         if (local == null)
         {
             return Collections.emptyList();
         }
         // this is cheap - it just wraps the collection
         return Collections.unmodifiableList(local);
     }
 
     public final boolean removeListener(IEventListener listener)
     {
         /*
          * If a component is not active, don't remove the listener; there may be
          * some events generated by this component during shutdown that should
          * be received by the listener. In any case, when this object is
          * released and GC'd, the collection of listeners will also be GC'd.
          */
         if (!isActive())
         {
             return false;
         }
         List<IEventListener> copy = null;
         boolean removed = false;
         // copy-on-write and ensure this is an atomic unit of work
         synchronized (this)
         {
             final List<IEventListener> local = this.listeners;
             if (local == null)
             {
                 return false;
             }
             copy = new ReferenceCountingList<IEventListener>(local);
             removed = copy.remove(listener);
             if (copy.size() == 0)
             {
                 this.listeners = null;
             }
             else
             {
                 this.listeners = copy;
             }
             if (removed)
             {
                 doPostRemoveListener(listener);
             }
         }
         if (removed)
         {
             try
             {
                 listener.removedAsListenerFrom(this);
             }
             catch (Exception e)
             {
                 logException(getLog(), this, e);
             }
             if (getLog().isDebugEnabled())
             {
                 getLog().debug(
                     "Removed listener " + safeToString(listener)
                         + " from source " + createIdentityString());
             }
         }
         return removed;
     }
 
     public final List<IEventListener> removeListeners()
     {
         synchronized (this)
         {
             final List<IEventListener> local = this.listeners;
             if (local == null)
             {
                 return Collections.emptyList();
             }
             // we need a copy because we're iterating and possibly removing
             final List<IEventListener> copy =
                 new ReferenceCountingList<IEventListener>(local);
             for (IEventListener eventListener : copy)
             {
                 try
                 {
                     removeListener(eventListener);
                 }
                 catch (Exception e)
                 {
                     logException(getLog(), eventListener, e);
                 }
             }
             return copy;
         }
     }
 
     /**
      * Hook to allow sub-classes to perform any post processing after an
      * {@link IEventListener} has been added via
      * {@link #addListener(IEventListener)}
      * 
      * @param listener
      *            the listener that has been added
      */
     protected void doPostAddListener(IEventListener listener)
     {
         // noop
     }
 
     /**
      * Hook to allow sub-classes to perform any post processing after an
      * {@link IEventListener} has been removed via
      * {@link #removeListener(IEventListener)}
      * 
      * @param listener
      *            the listener that has been removed
      */
     protected void doPostRemoveListener(IEventListener listener)
     {
         // noop
     }
 
     @Override
     protected void doStart()
     {
         // noop
     }
 
     @Override
     protected final void doDestroy()
     {
         if (!isClone())
         {
             doComponentDestroy();
         }
     }
 
     /**
      * The destroy method that is invoked on a non-cloned version of this.
      */
     protected void doComponentDestroy()
     {
         this.currentFrame = null;
         this.drivingFrame = null;
         // don't remove listeners otherwise we don't get any destroy events...
         // leave identity and sysId
     }
 
     /**
      * Check if this instance is a clone.
      * 
      * @throws IllegalStateException
      *             if this is a cloned instance.
      */
     protected final void checkClone()
     {
         if (isClone())
         {
             throw new IllegalStateException(
                 "This is a clone and cannot be altered");
         }
     }
 
     /**
      * Determine if this instance is the original or a clone
      * 
      * @return <code>true</code> if this is a clone of the original
      */
     public final boolean isClone()
     {
         return this.isClone == 1;
     }
 
     /**
      * Utility method to create the system identity string for a component.
      * 
      * @return the system identity string
      */
     protected final String createIdentityString()
     {
         return string(this, getAddress());
     }
 
     /**
      * Helper method to return the component's identity and whether it is a
      * clone or not
      * 
      * @return a string with the component's identity and whether its a clone or
      *         not
      */
     protected StringBuilder getIdentityString()
     {
         StringBuilder sb = new StringBuilder();
         sb.append((isClone == 1 ? "[clone]" : EMPTY_STRING)).append(
             getIdentity());
         return sb;
     }
 
     /**
      * Write the component state in its wire form to the buffer. <strong>Any
      * nested fields must be written by calling their
      * {@link #writeState(IOperationScope, IWireIdentity, byte[][], int[], byte[][], int[], boolean)}
      * method.</strong>
      * 
      * @see IWireState#writeState(IOperationScope, IWireIdentity, byte[][],
      *      int[], byte[][], int[], boolean)
      * @see ArrayUtils for a discussion of the byte[][] usage
      * @return true if the write operation succeeded
      * @throws Exception
      */
     protected abstract boolean doWriteState(IOperationScope scope,
         IWireIdentity wireId, byte[][] headerBuffer,
         int[] headerBufferPosition, byte[][] dataBuffer,
         int[] dataBufferPosition, boolean completeState) throws Exception;
 
     /**
      * Update the component state from the wire format state in the buffer.
      * <strong>Any nested fields must be read using their
      * {@link #readState(IOperationScope, byte[], int, int)} method.</strong>
      * 
      * @see IWireState#readState(IOperationScope, byte[], int, int)
      * @return true if the read operation succeded.
      * @throws Exception
      */
     protected abstract boolean doReadState(IOperationScope scope,
         byte[] buffer, int start, int numberOfBytes) throws Exception;
 
     public String toDetailedString()
     {
         return createIdentityString();
     }
 
     public String toIdentityString()
     {
         return createIdentityString();
     }
 
     public IEvent getTriggerEvent()
     {
         // noop
         return null;
     }
 
     public void setTriggerEvent(IEvent triggerEvent)
     {
         // noop
     }
 
     @Override
     protected AsyncLog getLog()
     {
         return LOG;
     }
 
     public final IAddressable getAddressable()
     {
         return id;
     }
 
     @Override
     public String toString()
     {
         return createIdentityString();
     }
 
     @Override
     public Object clone() throws CloneNotSupportedException
     {
         final AbstractComponent clone = (AbstractComponent) super.clone();
         clone.isClone = 1;
         clone.source = this;
         return clone;
     }
 
     @Override
     public int hashCode()
     {
         return this.getAddressable().hashCode();
     }
 
     @Override
     public boolean equals(Object obj)
     {
         return this.getAddressable().equals(obj);
     }
 }