/*
      Copyright 2008 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.context;
  
  import fulmine.IDomain;
  import fulmine.ILifeCycle;
  import fulmine.IType;
  import fulmine.distribution.IDistributionManager;
  import fulmine.distribution.connection.IConnectionBroker;
  import fulmine.distribution.connection.IConnectionDiscoverer;
  import fulmine.event.IEvent;
  import fulmine.event.IEventManager;
  import fulmine.event.IEventSource;
  import fulmine.event.listener.IEventListener;
  import fulmine.model.IModelManager;
  import fulmine.model.container.IContainer;
  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.rpc.IRpcManager;
  
  /**
   * This is the application context for fulmine, a distributed data model system
   * (DDMS). Application code uses a context to interact with the data model,
   * event and distribution framework.
   * 
   * <h2>Data model framework</h2> The data model is composed of
   * {@link IContainer} objects. These represent the data entities that the
   * context manages. The context keeps track of all containers created in this
   * context. Containers created in the context are keyed against their type and
   * identity. Changes to the containers can be observed using the event and
   * distribution framework (see next sections).
   * <p>
   * There are 2 types of container in the context; local and remote. A local
   * container is an instance that is created by local user code; the container is
   * native to this context. Local containers are created via
   * {@link IModelManager#getLocalContainer(String, IType, IDomain)}. A remote
   * container is a 'proxy' to a local container that is native to a remote
   * context. Any attempt by user code to alter a remote container's state will
   * generate an exception. A remote container is created by accessing the
   * {@link IModelManager#getRemoteContainer(String, String, IType, IDomain)}
   * method.
   * <p>
   * Containers have a unidirectional distributed state; only changes in a local
   * container are distributed to remote container instances. Remote containers
   * are, to all intents and purposes, read-only in the local context.
   * 
   * <h2>Event framework</h2>
   * The event framework is based on {@link IEventListener} instances registered
   * against {@link IEventSource} instances. The listeners receive the events
   * generated by the sources they are registered for. This is all in a single
   * process.
   * <p>
   * A key design principle is that an event source has an associated 'event
   * processor' thread that never changes. The processor is mapped to the event
   * source's type (see {@link IEventSource#getType()}). An event processor thread
   * may service multiple sources of different types. All listeners registered
   * against a source will be activated by the same thread when events are being
   * notified. This does not mean the listener is inherently thread safe; if it is
   * registered against 2 sources of 2 different types, there might be 2 threads
   * activating the listener. The only rule is that the same thread activates the
   * listener when notifying it with an event from the source the thread is
   * associated with.
   * <p>
   * The events framework is accessed via the following methods:
   * <ul>
   * <li>{@link #queueEvent(IEvent)} to notify a listener with an event from a
   * <li>
   * {@link IDistributionManager#subscribe(String, String, IType, IDomain, IEventListener)}
   * to register a listener for events from a source in a context
   * </ul>
   * The event framework can be used as an event distribution mechanism as
   * demonstrated by the following code snippet.
   * 
   * <pre>
   * // create the context
   * IFulmineContext context = new FulmineContext(&quot;context name&quot;);
   * context.start();
   * 
   * IEventListener listener = new CustomListener();
   * // subscribe for an event source
   * context.subscribe(&quot;context name&quot;, &quot;foobar&quot;, Type.get(99), Domain.get(12),
  *     listener);
  * 
  * // get the event source so we can trigger a change (a container is an event source)
  * IEventSource container =
  *     context.getLocalContainer(&quot;foobar&quot;, Type.get(99), Domain.get(12));
  * // generate an event from the event source
  * // note that CustomEvent extends AbstractEvent...
  * IEvent event = new CustomEvent(container);
  * context.queueEvent(event);
  * // the listener will receive the event in a separate thread - one of the context's event processors
  * </pre>
  * 
  * The data model framework interacts directly with the event framework and
  * allows user code to receive events from the data model. Containers
  * effectively raise events that encapsulate the latest change. The event will
  * be a <i>clone</i> of the container so listeners are not interacting with the
  * actual container. The following code snippet shows how to use the event
  * framework to listen for data model changes.
  * 
  * <pre>
  * // create the context
  * IFulmineContext context = new FulmineContext(&quot;context name&quot;);
  * context.start();
  * 
  * IEventListener listener = new CustomListener();
  * // subscribe for the container
  * context.subscribe(&quot;context name&quot;, &quot;foobar&quot;, Type.get(99), Domain.get(12),
  *     listener);
  * 
  * // get an event source (a container is an event source)
  * IEventSource container =
  *     context.getLocalContainer(&quot;foobar&quot;, Type.get(99), Domain.get(12));
  * // alter the container 
  * IntegerField field = new IntegerField(&quot;an integer component&quot;);
  * field.set(1);
  * container.add(field);
  * container.flushFrame();
  * // the listener will receive a clone of the container that has the field added
  * </pre>
  * 
  * <h2>Distribution framework</h2>
  * Out-of-process event distribution is only available for data model changes
  * (this was designed primarily as a distributed data model system). It requires
  * collaborating objects:
  * <ul>
  * <li>{@link IConnectionDiscoverer} - to find other remote contexts
  * <li>{@link IConnectionBroker} - to create a connection to the remote context
  * </ul>
  * The context must have these injected via the setter methods prior to being
  * started. Once started with the connection collaborators, the context is
  * remotely available and can receive data model changes to remote containers.
  * It can also distribute local container changes to remote contexts. The
  * distribution is achieved by a local context subscribing for a remote
  * container in a remote context, as demonstrated below
  * 
  * <pre>
  * IEventListener listener = new CustomListener();
  * // subscribe for the remote container from the remote context
  * // it is assumed that the remote context exists in this example 
  * context.subscribe(&quot;a remote context&quot;, &quot;foobar&quot;, Type.get(99), Domain.get(12),
  *     listener);
  * // the listener will now receive changes from the remote container
  * </pre>
  * 
  * <h3>Updating remote containers</h3>
  * 
  * A context can update a remote container only by invoking the
  * {@link #updateRemoteContainer(String, String, IType, IDomain, String, String)}
  * method. However, by default, a context will veto any attempt by a remote
  * context to update one of its local containers. To override this, application
  * code needs to provide a {@link IRemoteUpdateHandler} via the
  * {@link #setRemoteUpdateHandler(IRemoteUpdateHandler)} method. The permission
  * profile of the updating context is passed to the remote context during the
  * operation; if the permissions of the updating context are not compatible with
  * the field being updated, the operation will fail. The
  * {@link #updateRemoteContainer(String, String, IType, IDomain, String, String)}
  * method is in fact an RPC. RPC and permissions are described in the following
  * sections.
  * 
  * <h2>RPC framework</h2>
  * 
  * Remote procedures can be invoked on remote contexts. In the remote context,
  * application code must first register a procedure with the context. After
  * this, the procedure is published to any contexts that have subscribed for
  * registered RPCs.
  * <p>
  * The arguments for any RPC are limited to the 'native' types;
  * {@link IntegerField}, {@link StringField}, {@link LongField},
  * {@link DoubleField}, {@link FloatField}, {@link BooleanField}. The return
  * type for an RPC is also limited to the above types. The 'void' return type is
  * not supported.
  * <p>
  * See {@link RpcManager} for a more detailed description of the RPC
  * fundamentals. The following code snippet demonstrates invoking a RPC:
  * 
  * <pre>
  * // local context registers for RPCs from the remote context
  * context.addRpcPublicationListener(remoteContextIdentity, listener);
  * 
  * // ... assume an RPC has been picked up by the publication listener
  * // the RPC signature published is 'boolean helloWorld(String name)'
  * // note that the name of the StringField (or any args during the 
  * // invocation) are purely arbitrary
  * context.invoke(remoteContextIdentity, &quot;helloWorld&quot;, new StringField(&quot;name&quot;,
  *     &quot;lasers&quot;));
  * </pre>
  * 
  * <h2>Permissions</h2>
  * 
  * All data fields of a container include a permission profile. This allows the
  * context to control visibility of the data for other remote contexts. Further
  * information on the permissions is described in {@link IPermissionProfile}.
  * <p>
  * 
  * @author Ramon Servadei
  */
 public interface IFulmineContext extends ILifeCycle, IModelManager,
     IEventManager, IDistributionManager, IRpcManager
 {
 
     final static String NAME = "Fulmine";
 
     /**
      * Start the context. The context becomes active and usable after this
      * method completes. If a {@link IConnectionBroker} and
      * {@link IConnectionDiscoverer} have been provided via the relevant setter
      * methods, this context becomes remotely available.
      */
     void start();
 
     /**
      * Set the {@link INetwork} for the context. This allows the context to
      * communicate with other contexts that use the same network transport. This
      * must be called before {@link #start()}.
      * 
      * @param network
      *            the network
      */
     void setNetwork(INetwork network);
 
     /**
      * Set the component that will report on the state of this context
      * 
      * @param watchdog
      *            a component that can report on the state of this context
      */
     void setContextWatchdog(IContextWatchdog watchdog);
 
     /**
      * Set the permission profile for the context. This will define all the
      * {@link IField}s that this context will be allowed to view.
      * 
      * @param profile
      *            the permission profile
      */
     void setPermissionProfile(IPermissionProfile profile);
 
     /**
      * Get the permission profile for the context. This defines all the
      * {@link IField}s that this context is allowed to view. If a profile has
      * not been set by application code, a default one should be provided.
      * 
      * @return the permission profile for this context
      */
     IPermissionProfile getPermissionProfile();
 
     /**
      * Get the unique identity of this context. In a network of contexts, the
      * identity must by unique.
      * 
      * @return the identity for this context
      */
     String getIdentity();
 
     /**
      * Get a unique integer for this context. This must be completely unique
      * across all distributed context instances in the network, regardless of
      * the context identity. This integer can be used to uniquely identify this
      * context instance within the network.
      * 
      * @return a unique integer for the context
      */
     int getContextHashCode();
 
     /**
      * Set the object that will handle updates to local records from remote
      * contexts via RPC calls. By default a vetoing updater is used that
      * prevents remote contexts from updating local records via RPC calls.
      * 
      * @see IDistributionManager#updateRemoteContainer(String, String, IType,
      *      IDomain, String, String)
      * 
      * @param handler
      *            the handler to use
      */
     void setRemoteUpdateHandler(IRemoteUpdateHandler handler);
 }