/**
 * 
 */
package uk.ac.vamsas.objects;

import uk.ac.vamsas.client.Vobject;
import uk.ac.vamsas.client.VorbaId;

/**
 * Provides methods to map between VorbaIds and arbitrary object references
 * for use by a vamsas Application when moving between its own datamodel and the
 * Vamsas session objects.
 * The implementing class needs a valid client-document instance if it is expected
 * to be able to register newly created vObjects. Normally this will be the case if
 * the implementing class has been generated by an IClient implementation which will
 * also have passed it a reference to the current valid IClientDocument instance for
 * that application's document access thread. 
 * TODO: add remove/clear binding functions - currently you can just pass a null
 * to either argument for bindAppsObjectToVamsasObject to remove the binding from memory. 
 * @author JimP
 * 
 */
public interface IVorbaBinding {
/**
 * get the Vamsas session object bound to an internal object.
 * @param appObject
 * @return valid session object or Null.
 */
  Vobject getVamsasObjectFor(Object appObject);
  /**
   * Get the Application's own object bound to an existing Vamsas session object
   * @param vObject - object in vamsas document
   * @return apps object bound to the vamsas document object
   */
  Object getAppsObjectFor(uk.ac.vamsas.client.Vobject vObject);

  /**
   * Record a mapping between a vamsas document object and an application's internal object.
   * If either appObject or vObject parameters are null then any existing 
   * binding to the non-null object will be deleted
   * @param appObject
   * @param vObject - if newly created then it will be registered using the uk.ac.vamsas.client.IClientDocument.registerObject method.
   */
  void bindAppsObjectToVamsasObject(Object appObject, uk.ac.vamsas.client.Vobject vObject);
}