/*
      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.container;
  
  import static fulmine.util.Utils.CLOSE_SQUARE;
  import static fulmine.util.Utils.COMMA;
  import static fulmine.util.Utils.EMPTY_STRING;
  import static fulmine.util.Utils.EQUALS;
  import static fulmine.util.Utils.OPEN_SQUARE;
  import static fulmine.util.Utils.SPACE;
  import static fulmine.util.Utils.SPACING_4_CHARS;
  import static fulmine.util.Utils.logException;
  import static fulmine.util.Utils.nullCheck;
  import static fulmine.util.Utils.safeToString;
  
  import java.util.Collection;
  import java.util.Collections;
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  import java.util.Map.Entry;
  
  import org.apache.commons.lang.SystemUtils;
  
  import fulmine.IDomain;
  import fulmine.IType;
  import fulmine.context.IFrameworkContext;
  import fulmine.event.EventFrameExecution;
  import fulmine.event.IEventFrameExecution;
  import fulmine.event.listener.IEventListener;
  import fulmine.event.system.EventSourceNotObservedEvent;
  import fulmine.event.system.EventSourceObservedEvent;
  import fulmine.model.component.AbstractComponent;
  import fulmine.model.container.events.ContainerCreatedEvent;
  import fulmine.model.container.events.ContainerDestroyedEvent;
  import fulmine.model.container.events.ContainerStateChangeEvent;
  import fulmine.model.container.events.RemoteContainerCreatedEvent;
  import fulmine.model.container.events.RemoteContainerDestroyedEvent;
  import fulmine.model.field.BooleanField;
  import fulmine.model.field.DoubleField;
  import fulmine.model.field.FloatField;
  import fulmine.model.field.IField;
  import fulmine.model.field.IntegerField;
  import fulmine.model.field.LongField;
  import fulmine.model.field.StringField;
  import fulmine.model.field.containerdefinition.IContainerDefinitionField;
  import fulmine.protocol.specification.FieldReader;
  import fulmine.protocol.specification.FrameReader;
  import fulmine.protocol.specification.FrameWriter;
  import fulmine.protocol.wire.IWireIdentity;
  import fulmine.protocol.wire.operation.IOperationScope;
  import fulmine.util.Utils;
  import fulmine.util.collection.CollectionFactory;
  import fulmine.util.log.AsyncLog;
  
  /**
   * The base class for containers.
   * <p>
   * This implementation is thread safe. The the {@link #add(IField)} and
   * {@link #remove(IField)} methods perform copy-on-write operations. The
   * {@link Collection} for the fields uses the <a
   * href="http://www.ibm.com/developerworks/java/library/j-jtp06197.html" >'cheap
   * read-write lock'</a>
   * <p>
   * This implementation can read and write itself from and to a wire frame.
   * However, when writing, it writes a complete image of itself (i.e. all its
   * internal {@link IField} objects are written, regardless of any changes that
   * have occurred). Sub-classes may override this to in a more efficient
   * mechanism that only writes changed internal fields (deltas).
   * 
   * @author Ramon Servadei
   * 
   */
  public abstract class AbstractContainer extends AbstractComponent implements
      IContainer, Cloneable
  {
      private final static AsyncLog LOG = new AsyncLog(AbstractContainer.class);
  
      /**
       * The reader task executed by the {@link FieldReader} when reading messages
       */
      protected class ReaderTask implements FieldReader.IFieldReaderTask
      {
          public void read(IOperationScope scope, int fieldId, byte[] dataBuffer,
              int dataStart, int dataLen)
          {
             final AbstractContainer outer = AbstractContainer.this;
             try
             {
                 IField field =
                     outer.fields.get(getDefinition().getIdentityForWireCode(
                         fieldId));
                 boolean addToContainer = false;
                 if (field == null)
                 {
                     // try to create it
                     if (getDefinition().containsDefinition(fieldId))
                     {
                         field = getDefinition().createField(fieldId);
                         addToContainer = true;
                     }
                 }
                 if (field != null)
                 {
                     field.readState(scope, dataBuffer, dataStart, dataLen);
                     if (addToContainer)
                     {
                         /*
                          * Only add the field once it has read its state,
                          * otherwise if we added the field simply when it was
                          * created from the definition, it would have no value
                          * and we'd raise a ContainerFieldAddedEvent with the
                          * field but no value - pretty useless really.
                          */
                         add(field);
                     }
                 }
                 else
                 {
                     /*
                      * If this is a remote container and has been destroyed, we
                      * may receive delayed wire messages
                      */
                     if (getLog().isInfoEnabled())
                     {
                         getLog().info(
                             "No field found for field id="
                                 + fieldId
                                 + ", container="
                                 + outer.toIdentityString()
                                 + ", fields="
                                 + outer.fields
                                 + ". This might be a delayed wire frame received "
                                 + "AFTER the remote container was destroyed.");
                     }
                 }
             }
             catch (Exception e)
             {
                 // todo request a retransmission
                 outer.getContext().requestRetransmit(
                     outer.getNativeContextIdentity(), outer.getIdentity(),
                     outer.getType(), outer.getDomain());
                 throw new IllegalStateException(
                     "Could not read state for field id=" + fieldId
                         + ", container=" + outer.toIdentityString()
                         + ", fields=" + outer.fields
                         + ". Has an image message been missed? "
                         + "Automatically requesting a retransmission.", e);
             }
         }
 
         public void read(IOperationScope scope, String fieldId,
             byte[] dataBuffer, int dataStart, int dataLen)
         {
             throw new IllegalStateException(
                 "reading SWF fields is invalid for a container");
         }
 
     }
 
     /**
      * Tracks the count of remote subscriptions to this instance. Uses the <a
      * href="http://www.ibm.com/developerworks/java/library/j-jtp06197.html"
      * >'cheap read-write lock'</a>
      */
     private volatile byte remoteSubscriptionCount;
 
     /**
      * A thread local variable to hold the {@link IEventFrameExecution} of the
      * current event frame. This is bound to the thread executing the event
      * frame.
      */
     private final ThreadLocal<IEventFrameExecution> frameIdentifier =
         new ThreadLocal<IEventFrameExecution>();
 
     /**
      * The current thread executing an event frame. Uses the <a
      * href="http://www.ibm.com/developerworks/java/library/j-jtp06197.html"
      * >'cheap read-write lock'</a>
      */
     volatile Thread eventFrameThread;
 
     /** Tracks multiple calls to {@link #lockFrame()} */
     private byte eventFrameLockCount;
 
     /**
      * The {@link IField} objects this container holds, indexed by their
      * {@link String} identity. Uses the <a
      * href="http://www.ibm.com/developerworks/java/library/j-jtp06197.html"
      * >'cheap read-write lock'</a>
      */
     private volatile Map<String, IField> fields;
 
     /**
      * The state (validity) of the container. Uses the <a
      * href="http://www.ibm.com/developerworks/java/library/j-jtp06197.html"
      * >'cheap read-write lock'</a>
      */
     private volatile DataState dataState;
 
     /**
      * The name of the context this container is native to. If the container is
      * local, its native context will be the same as the hosted context
      * identity.
      */
     private final String nativeContextIdentity;
 
     /** The context hosting this container instance */
     private final IFrameworkContext hostContext;
 
     /** Whether the container is local to the host context */
     private final boolean local;
 
     /**
      * Standard constructor. The container is marked as {@link IContainer#LIVE
      * LIVE}. If a {@link EventThread} is constructing this then the container
      * is a remote container.
      * 
      * @param nativeContextIdentity
      *            the name of the context this container is native to - the name
      *            of its local context
      * @param identity
      *            the identity of the container
      * @param type
      *            the type of the container
      * @param domain
      *            the domain for the container
      * @param hostContext
      *            the context hosting this container instance
      * @param local
      *            <code>true</code> the container is local to this context
      * @see ContainerFactory
      */
     public AbstractContainer(String nativeContextIdentity, String identity,
         IType type, IDomain domain, IFrameworkContext hostContext, boolean local)
     {
         // only an abstract container is an event source
         // note: we do not use the 0th (zeroth) processor as this is used for
         // the system events
         super(
             identity,
             type,
             domain,
             // bind the container type to an event processor
             (byte) ((type.value() % (hostContext.getEventProcessorCount() - 1)) + 1));
         this.fields = CollectionFactory.newMap(1);
         this.dataState = DataState.LIVE;
         nullCheck(hostContext, "A hosted context is required");
         Utils.nullCheck(nativeContextIdentity, "The native context is required");
         this.hostContext = hostContext;
         this.nativeContextIdentity = nativeContextIdentity;
         this.local = local;
         // is this a local container
         if (!isLocal())
         {
             this.dataState = DataState.STALE;
         }
         getContext().addContainer(this);
     }
 
     @Override
     protected AsyncLog getLog()
     {
         return LOG;
     }
 
     @Override
     protected final void doStart()
     {
         super.doStart();
         getDefinition().populate(this);
         if (isLocal())
         {
             getContext().queueEvent(
                 new ContainerCreatedEvent(getContext(), this));
         }
         else
         {
             /*
              * for a remote container, notify the listeners synchronously...
              * this is so that any subscriptions are registered against the
              * remote container BEFORE any remote changes are then processed.
              */
             final List<IEventListener> rcceListeners =
                 getContext().getSystemEventSource(
                     RemoteContainerCreatedEvent.class).getListeners();
             for (IEventListener eventListener : rcceListeners)
             {
                 eventListener.update(new RemoteContainerCreatedEvent(
                     getNativeContextIdentity(), getContext(), this));
             }
         }
     }
 
     @Override
     protected void doComponentDestroy()
     {
         if (getLog().isInfoEnabled())
         {
             getLog().info("Destroying " + getAddressable());
         }
         // ensure we don't interfere with another thread doing some work
         boolean clearFrameReaderContext = false;
         if (!FrameReader.inContext())
         {
             clearFrameReaderContext = true;
             FrameReader.inContext.set(Boolean.TRUE);
         }
         try
         {
             beginFrame(new EventFrameExecution("destroy " + getAddress()));
             try
             {
                 super.doComponentDestroy();
                 setState(DataState.STALE);
                 final Collection<IField> values;
                 // copy-on-write to 'clear' the field map
                 synchronized (this)
                 {
                     values = CollectionFactory.newList(this.fields.values());
                     this.fields = Collections.emptyMap();
                 }
                 for (IField field : values)
                 {
                     try
                     {
                         field.destroy();
                     }
                     catch (Exception e)
                     {
                         logException(getLog(), field, e);
                     }
                 }
                 if (getContext() != null && getContext().isActive())
                 {
                     if (isLocal())
                     {
                         getContext().queueEvent(
                             new ContainerDestroyedEvent(getContext(), this));
                     }
                     else
                     {
                         getContext().queueEvent(
                             new RemoteContainerDestroyedEvent(
                                 getNativeContextIdentity(), getContext(), this));
                     }
                     // finally remove the container from the context
                     getContext().removeContainer(this);
                 }
             }
             finally
             {
                 endFrame();
             }
         }
         finally
         {
             if (clearFrameReaderContext)
             {
                 FrameReader.inContext.remove();
             }
         }
     }
 
     public final boolean isRemote()
     {
         return !isLocal();
     }
 
     public final IFrameworkContext getContext()
     {
         return this.hostContext;
     }
 
     public final String getNativeContextIdentity()
     {
         return this.nativeContextIdentity;
     }
 
     public final void add(IField field)
     {
         checkIsLocalOrInFrameReaderContext();
         doAdd(field);
     }
 
     void doAdd(IField field)
     {
         // copy-on-add and ensure atomic operation
         synchronized (this)
         {
             beforeAdd(field);
             final Map<String, IField> copy =
                 CollectionFactory.newMap(this.fields);
             copy.put(field.getIdentity(), field);
             this.fields = copy;
             afterAdd(field);
         }
         field.addedToContainer(this);
     }
 
     /**
      * Called before the field is added. This is called whilst holding the
      * monitor lock for adding/removing fields.
      * 
      * @param field
      *            the field to add
      */
     protected void beforeAdd(IField field)
     {
     }
 
     /**
      * Called after the field is added and the copy-on-write operation has
      * completed. This is called whilst holding the monitor lock for
      * adding/removing fields.
      * 
      * @param field
      *            the field to add
      */
     protected void afterAdd(IField field)
     {
     }
 
     public final <T extends IField> T remove(T field)
     {
         checkIsLocalOrInFrameReaderContext();
         return doRemove(field);
     }
 
     @SuppressWarnings("unchecked")
     <T extends IField> T doRemove(T field)
     {
         IField removed = null;
         // copy-on-remove and ensure atomic operation
         synchronized (this)
         {
             beforeRemove(field);
             final Map<String, IField> copy =
                 CollectionFactory.newMap(this.fields);
             removed = copy.remove(field.getIdentity());
             this.fields = copy;
             afterRemove(field, removed);
         }
         field.removedFromContainer(this);
         return (T) removed;
     }
 
     /**
      * Called before the field is removed. This is called whilst holding the
      * monitor lock for adding/removing fields.
      * 
      * @param field
      *            the field to remove
      */
     protected void beforeRemove(IField field)
     {
     }
 
     /**
      * Called after the field is removed and the copy-on-write operation has
      * completed. This is called whilst holding the monitor lock for
      * adding/removing fields.
      * 
      * @param field
      *            the field to remove
      * @param removed
      *            the field that has been removed - if <code>null</code> then
      *            the field was not removed (possibly because it was not in the
      *            fields)
      */
     protected void afterRemove(IField field, IField removed)
     {
 
     }
 
     public final boolean isEmpty()
     {
         return this.fields.isEmpty();
     }
 
     public final boolean contains(String key)
     {
         return this.fields.containsKey(key);
     }
 
     public final int size()
     {
         return this.fields.size();
     }
 
     @SuppressWarnings("unchecked")
     public final <T extends IField> T get(String identity)
     {
         final IField field = this.fields.get(identity);
         return (T) field;
     }
 
     public final String[] getComponentIdentities()
     {
         final Set<String> keySet = this.fields.keySet();
         return keySet.toArray(new String[keySet.size()]);
     }
 
     public final void beginFrame(IEventFrameExecution frame)
     {
         if (isEventFrameThread())
         {
             throw new IllegalStateException(
                 "Cannot start a new frame before completing an existing one");
         }
         checkIsLocalOrInFrameReaderContext();
         lockFrame();
         // set the frame identifier
         this.frameIdentifier.set(frame);
     }
 
     public final void endFrame()
     {
         checkIsLocalOrInFrameReaderContext();
         if (isEventFrameThread())
         {
             try
             {
                 doCommitEvents();
             }
             finally
             {
                 unlockFrame();
             }
         }
         else
         {
             logNotTheEventFrameThread();
         }
     }
 
     public final void flushFrame()
     {
         if (!isEventFrameThread())
         {
             beginFrame(new EventFrameExecution());
         }
         if (isEventFrameThread())
         {
             endFrame();
         }
         else
         {
             logNotTheEventFrameThread();
         }
     }
 
     public final boolean isFrameActive()
     {
         return this.eventFrameThread != null;
     }
 
     public final void setState(DataState stateCode)
     {
         DataState oldState = this.dataState;
         boolean update = oldState != stateCode;
         synchronized (this)
         {
             this.dataState = stateCode;
         }
         if (update)
         {
             doStateChangeOp(oldState);
             /*
              * When triggering an update, we need to masquerade as being in a
              * frame reader context if this is a remote container
              */
             if (!isEventFrameThread())
             {
                 boolean clearFrameReaderContext = false;
                 if (!FrameReader.inContext())
                 {
                     clearFrameReaderContext = true;
                     FrameReader.inContext.set(Boolean.TRUE);
                 }
                 try
                 {
                     // trigger the update
                     flushFrame();
                 }
                 finally
                 {
                     if (clearFrameReaderContext)
                     {
                         FrameReader.inContext.remove();
                     }
                 }
             }
         }
     }
 
     /**
      * Perform the operation when the {@link #dataState} changes.
      * 
      * @param oldState
      *            the old state
      */
     protected void doStateChangeOp(DataState oldState)
     {
         if (getContext() != null && getContext().isActive())
         {
             getContext().queueEvent(
                 new ContainerStateChangeEvent(getContext(), this,
                     this.dataState, oldState));
         }
     }
 
     public final DataState getDataState()
     {
         return this.dataState;
     }
 
     public boolean isDynamic()
     {
         return false;
     }
 
     public final boolean isLocal()
     {
         return this.local;
     }
 
     public int markForRemoteSubscription()
     {
         int count = 0;
         // uses the 'cheap read-write lock'
         // http://www.ibm.com/developerworks/java/library/j-jtp06197.html
         synchronized (this)
         {
             this.remoteSubscriptionCount++;
             count = this.remoteSubscriptionCount;
         }
         if (getLog().isInfoEnabled())
         {
             getLog().info(
                 "[mark] remote subscription count is " + count + " for "
                     + toIdentityString());
 
         }
         return count;
     }
 
     public int unmarkForRemoteSubscription()
     {
         int count = 0;
         // uses the 'cheap read-write lock'
         // http://www.ibm.com/developerworks/java/library/j-jtp06197.html
         synchronized (this)
         {
             this.remoteSubscriptionCount--;
             if (this.remoteSubscriptionCount < 0)
             {
                 this.remoteSubscriptionCount = 0;
             }
             count = this.remoteSubscriptionCount;
         }
         if (getLog().isInfoEnabled())
         {
             getLog().info(
                 "[unmark] remote subscription count is " + count + " for "
                     + toIdentityString());
         }
         return count;
     }
 
     public int getRemoteSubscriptionCount()
     {
         return this.remoteSubscriptionCount;
     }
 
     /**
      * Get the {@link BooleanField} identified by the identity
      * 
      * @param identity
      *            the identity of the field to get
      * @return the {@link BooleanField} for the identity
      * @throws ClassCastException
      *             if the field is not of this type
      */
     public BooleanField getBooleanField(String identity)
     {
         return get(identity);
     }
 
     /**
      * Get the {@link StringField} identified by the identity
      * 
      * @param identity
      *            the identity of the field to get
      * @return the {@link StringField} for the identity
      * @throws ClassCastException
      *             if the field is not of this type
      */
     public StringField getStringField(String identity)
     {
         return get(identity);
     }
 
     /**
      * Get the {@link IntegerField} identified by the identity
      * 
      * @param identity
      *            the identity of the field to get
      * @return the {@link IntegerField} for the identity
      * @throws ClassCastException
      *             if the field is not of this type
      */
     public IntegerField getIntegerField(String identity)
     {
         return get(identity);
     }
 
     /**
      * Get the {@link LongField} identified by the identity
      * 
      * @param identity
      *            the identity of the field to get
      * @return the {@link LongField} for the identity
      * @throws ClassCastException
      *             if the field is not of this type
      */
     public LongField getLongField(String identity)
     {
         return get(identity);
     }
 
     /**
      * Get the {@link FloatField} identified by the identity
      * 
      * @param identity
      *            the identity of the field to get
      * @return the {@link FloatField} for the identity
      * @throws ClassCastException
      *             if the field is not of this type
      */
     public FloatField getFloatField(String identity)
     {
         return get(identity);
     }
 
     /**
      * Get the {@link DoubleField} identified by the identity
      * 
      * @param identity
      *            the identity of the field to get
      * @return the {@link DoubleField} for the identity
      * @throws ClassCastException
      *             if the field is not of this type
      */
     public DoubleField getDoubleField(String identity)
     {
         return get(identity);
     }
 
     @Override
     protected final void doPostAddListener(IEventListener listener)
     {
         super.doPostAddListener(listener);
         // trigger the event source observed event when the first listener is
         // added
         if (getListeners().size() == 1)
         {
             getContext().queueEvent(
                 new EventSourceObservedEvent(getContext(), this));
         }
     }
 
     @Override
     protected final void doPostRemoveListener(IEventListener listener)
     {
         super.doPostRemoveListener(listener);
         // the context can be null if this container has been removed
         if (getListeners().size() == 0 && getContext() != null)
         {
             getContext().queueEvent(
                 new EventSourceNotObservedEvent(getNativeContextIdentity(),
                     getContext(), this));
         }
     }
 
     /**
      * Lock the event frame. This sets the {@link #eventFrameThread} to the
      * current thread. If there already is an event frame thread, this method
      * loops until the frame is unlocked.
      * 
      * @see #unlockFrame()
      */
     protected final void lockFrame()
     {
         synchronized (this)
         {
             while (this.eventFrameThread != null && !isEventFrameThread())
             {
                 if (getLog().isDebugEnabled())
                 {
                     getLog().debug(
                         "Waiting for " + this.eventFrameThread
                             + " to complete event frame for " + this,
                         new Exception());
                 }
                 else
                 {
                     if (getLog().isInfoEnabled())
                     {
                         getLog().info(
                             "Waiting for " + this.eventFrameThread
                                 + " to complete event frame for "
                                 + toIdentityString());
                     }
                 }
                 try
                 {
                     this.wait(500);
                 }
                 catch (InterruptedException e)
                 {
                     getLog().debug(e);
                 }
             }
             this.eventFrameThread = Thread.currentThread();
             this.eventFrameLockCount++;
         }
     }
 
     /**
      * Get the definition for this container. This effectively provides the
      * 'type' for the this container.
      * 
      * @return the {@link IContainerDefinitionField} that defines the
      *         {@link IField} objects (fields) of this container.
      * 
      */
     protected IContainerDefinitionField getDefinition()
     {
         return getContext().getContainerFactory().getDefinition(getType());
     }
 
     @Override
     protected boolean doReadState(IOperationScope scope, byte[] buffer,
         int start, int numberOfBytes) throws Exception
     {
         lockFrame();
         try
         {
             int[] headerStart = new int[1];
             int[] headerLen = new int[1];
             int[] dataStart = new int[1];
             int[] dataLen = new int[1];
 
             // find out how big the header buffer and data buffer are
             FrameReader.findHeaderAndDataBufferPositions(buffer, start,
                 headerStart, headerLen, dataStart, dataLen);
 
             if (headerLen[0] == 0)
             {
                 // an empty frame or meta data for the container
                 return true;
             }
             FieldReader.readIWFFieldSpecs(scope, buffer, headerStart[0],
                 headerLen[0], dataStart[0], dataLen[0], newReaderTask());
         }
         finally
         {
             unlockFrame();
         }
         return true;
     }
 
     /**
      * Get the reader task to use during the
      * {@link #doReadState(IOperationScope, byte[], int, int)} method. The
      * reader task is executed for each field spec found during the read state
      * operation. The task implementation is responsible for
      * constructing/reading the {@link IField} expressed in the field spec.
      * 
      * @return the {@link ReaderTask} to invoke for each field spec found during
      *         the read state operation.
      */
     protected ReaderTask newReaderTask()
     {
         return this.new ReaderTask();
     }
 
     @Override
     protected boolean doWriteState(IOperationScope scope, IWireIdentity wireId,
         byte[][] headerBuffer, int[] headerBufferPosition, byte[][] dataBuffer,
         int[] dataBufferPosition, boolean completeState) throws Exception
     {
         // only local entities are written to the wire (unidirectional changes)
         // remote entities are read-only
         if (isLocal())
         {
             lockFrame();
             try
             {
                 final Collection<IField> fieldsToWrite;
                 if (getDataState() == DataState.STALE)
                 {
                     // no changes should be sent in this state
                     fieldsToWrite = Collections.emptySet();
                 }
                 else
                 {
                     fieldsToWrite = getFieldsToWrite(completeState);
                 }
                 FrameWriter.writeHeaderAndData(this, fieldsToWrite,
                     getDefinition(), scope, headerBuffer, headerBufferPosition,
                     dataBuffer, dataBufferPosition, completeState);
             }
             catch (IllegalArgumentException e)
             {
                 throw new IllegalArgumentException("Could not write field: "
                     + this, e);
             }
             finally
             {
                 unlockFrame();
             }
         }
         return true;
     }
 
     /**
      * Get the fields to write to a frame. This occurs whilst the event frame is
      * locked. This method allows sub-classes to inspect and mutate the
      * {@link #changedFields} field prior to being written to a frame.
      * 
      * @param completeState
      * 
      * @return the fields to write into a frame
      */
     protected Collection<IField> getFieldsToWrite(boolean completeState)
     {
         return this.fields.values();
     }
 
     /**
      * Is the executing thread the event frame thread.
      * 
      * @return <code>true</code> if the executing thread is the event frame
      *         thread.
      */
     protected final boolean isEventFrameThread()
     {
         return this.eventFrameThread == Thread.currentThread();
     }
 
     /**
      * Logs an exception and the current event frame thread.
      */
     protected void logNotTheEventFrameThread()
     {
         logException(getLog(), "The current thread is not the "
             + "event frame thread, the event frame thread is "
             + this.eventFrameThread + ". The current thread cannot execute "
             + safeToString(this), new IllegalStateException());
     }
 
     /**
      * Unlock the event frame. This clears the {@link #eventFrameThread} and
      * {@link #frameIdentifier}.
      * 
      * @see #lockFrame()
      */
     final void unlockFrame()
     {
         synchronized (this)
         {
             if (isEventFrameThread())
             {
                 this.eventFrameLockCount--;
                 if (this.eventFrameLockCount < 0)
                 {
                     this.eventFrameLockCount = 0;
                 }
                 if (this.eventFrameLockCount == 0)
                 {
                     this.eventFrameThread = null;
                     this.frameIdentifier.remove();
                 }
                 this.notify();
             }
             else
             {
                 logNotTheEventFrameThread();
             }
         }
     }
 
     /**
      * Check the container is local or the thread is in a {@link FrameReader}
      * context.
      */
     private final void checkIsLocalOrInFrameReaderContext()
     {
         if (!isLocal() && !FrameReader.inContext())
         {
             throw new IllegalStateException(
                 "Only a thread running in a FrameReader context can run this method on remote container "
                     + this);
         }
         checkClone();
     }
 
     @Override
     public String toDetailedString()
     {
         return containerToFormattedString(super.toDetailedString(), true);
     }
 
     /**
      * Return a nicely formatted string with the container fields printed using
      * their {@link AbstractComponent#toSimpleString()}
      * 
      * @param containerIdentity
      *            the identity string to use for the container
      * @param linePerField
      *            whether each field should be on a new line
      * @return a formatted string
      */
     private String containerToFormattedString(String containerIdentity,
         boolean linePerField)
     {
         StringBuilder sb = new StringBuilder();
         List<String> identities = CollectionFactory.newList(this.fields.size());
         // iterate over a copy
         Map<String, IField> copy = Collections.emptyMap();
         synchronized (this)
         {
             copy = CollectionFactory.newMap(this.fields);
         }
         if (isActive())
         {
             for (Entry<String, IField> entry : copy.entrySet())
             {
                 try
                 {
                     if (!getDefinition().equals(entry.getValue()))
                     {
                         identities.add(entry.getKey());
                     }
                 }
                 catch (Exception e)
                 {
                     logException(getLog(), entry, e);
                 }
             }
         }
         Collections.sort(identities);
         if (linePerField)
         {
             sb.append(SystemUtils.LINE_SEPARATOR);
         }
         sb.append(OPEN_SQUARE);
         if (linePerField)
         {
             sb.append(SystemUtils.LINE_SEPARATOR).append(SPACING_4_CHARS);
         }
         sb.append("nativeContext=").append(getNativeContextIdentity());
         sb.append(", state=").append(getDataState());
         if (linePerField)
         {
             sb.append(SystemUtils.LINE_SEPARATOR);
         }
         if (identities.size() > 0)
         {
             for (String string : identities)
             {
                 try
                 {
                     if (!linePerField)
                     {
                         sb.append(COMMA).append(SPACE);
                     }
                     else
                     {
                         sb.append(SPACING_4_CHARS);
                     }
                     sb.append(toString(copy.get(string)));
                     if (linePerField)
                     {
                         sb.append(SystemUtils.LINE_SEPARATOR);
                     }
                 }
                 catch (Exception e)
                 {
                     logException(getLog(), string, e);
                 }
             }
         }
         sb.append(CLOSE_SQUARE);
         if (linePerField)
         {
             sb.append(SystemUtils.LINE_SEPARATOR);
         }
         return (linePerField ? SystemUtils.LINE_SEPARATOR : EMPTY_STRING)
             + containerIdentity + EQUALS + sb.toString();
     }
 
     /**
      * @return A thread local variable to hold the {@link IEventFrameExecution}
      *         of the current event frame. This is bound to the thread executing
      *         the event frame.
      */
     protected ThreadLocal<IEventFrameExecution> getFrameIdentifier()
     {
         return this.frameIdentifier;
     }
 
     /**
      * @return The {@link IField} objects this container holds, indexed by their
      *         {@link String} identity. Uses the <a
      *         href="http://www.ibm.com/developerworks/java/library/j-jtp06197.html"
      *         >'cheap read-write lock'</a>
      */
     protected Map<String, IField> getFields()
     {
         return this.fields;
     }
 
     /**
      * @see #getFields()
      * @param fields
      */
     void setFields(Map<String, IField> fields)
     {
         this.fields = fields;
     }
 
     private String toString(IField field)
     {
         return field.getIdentity() + EQUALS + field.getValueAsString();
     }
 
     @Override
     public Object clone() throws CloneNotSupportedException
     {
         final AbstractContainer clone = (AbstractContainer) super.clone();
         clone.eventFrameThread = null;
         clone.fields = CollectionFactory.newMap(this.fields.size());
         // clone the fields
         final Set<Entry<String, IField>> entrySet = this.fields.entrySet();
         for (Entry<String, IField> entry : entrySet)
         {
             try
             {
                 clone.fields.put(entry.getKey(),
                     ((IField) entry.getValue().clone()));
             }
             catch (Exception e)
             {
                 logException(getLog(), entry, e);
             }
         }
         return clone;
     }
 
     @Override
     public final String toString()
     {
         return containerToFormattedString(super.toString(), false);
     }
 
     @Override
     public final int hashCode()
     {
         return super.hashCode();
     }
 
     @Override
     public final boolean equals(Object obj)
     {
         return super.equals(obj);
     }
 
     /**
      * Perform the operation to commit all events
      */
     protected void doCommitEvents()
     {
         // noop
     }
 
 }