package fractal.api;

/**
 * A component interface to control the content of the component to which it
 * belongs. This content is supposed to be made of an unordered, unstructured
 * set of components and bindings.
 */
interface ContentController extends ErrorConst {

  /**
   * Returns the sub-components of the component to which this
   * interface belongs. More precisely, if the given <code>subComponents</code>
   * is <code>null</code>, this method returns the number of sub components. 
   * If it is not <code>null</code>, this method assumes that the given array is
   * big enough to contain all the references to the {@link Component} 
   * interfaces of the sub components.
   *
   * @param subComponents an array into which the references to the 
   *      {@link Component} interfaces of the sub components are copied. Can be 
   *      <code>null</code>.
   * @return the number of sub components; or
   *      {@link ErrorConst#OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int getFcSubComponents(in Component[] subComponents);
	
  /**
   * Adds a sub-component to this component. More precisely adds the component
   * whose reference is given as a sub-component of the component to which this
   * interface belongs. If <i>C</i> is the sub-component set returned by {@link
   * #getFcSubComponents getFcSubComponents} just before a call to this
   * method, and <i>C'</i> is the sub-component set just after this call, then
   * <code>subComponent</code> is guaranteed to be in <i>C'</i>, but <i>C'</i> 
   * is <i>not</i> guaranteed to be the union of <i>C</i> and 
   * <i>{subComponent}</i>, nor to contain all the elements of <i>C</i>.
   *
   * @param subComponent the component to be added inside this component.
   * @return <code>0</code> if the component is added correctly. 
   *      {@link ErrorConst#ILLEGAL_CONTENT} if the component cannot be added. 
   *      {@link ErrorConst#ILLEGAL_LIFE_CYCLE} if this component has a 
   *      {@link LifeCycleController} interface, but it is not in an appropriate
   *      state to perform this operation.
   *      {@link ErrorConst#OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int addFcSubComponent(in Component subComponent);
	
  /**
   * Removes a sub-component from this component. More precisely removes the
   * sub-component whose reference is given from the component to which this
   * interface belongs. If <i>C</i> is the sub-component set returned by {@link
   * #getFcSubComponents getFcSubComponents} just before a call to this
   * method, and <i>C'</i> is the sub-component set just after this call, then
   * <code>subComponent</code> is guaranteed not to be in <i>C'</i>, but 
   * <i>C'</i> is <i>not</i> guaranteed to be the difference of <i>C</i> and
   * <i>{subComponent}</i>, nor to contain all the elements of <i>C</i> distinct
   * from <code>subComponent</code>.
   *
   * @param subComponent the component to be removed from this component.
   * @return <code>0</code> if the component has been removed correctly. 
   *      {@link ErrorConst#ILLEGAL_CONTENT} if the component cannot be removed. 
   *      {@link ErrorConst#NO_SUCH_SUB_COMPONENT} if the given 
   *      <code>subComponent</code> is not a sub component. 
   *      {@link ErrorConst#ILLEGAL_LIFE_CYCLE} if this component has a 
   *      {@link LifeCycleController} interface, but it is not in an appropriate
   *      state to perform this operation.
   *      {@link ErrorConst#OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int removeFcSubComponent(in Component subComponent);

  /**
   * Creates a binding inside this component.
   *
   * @param clientComponent the component that contains the client interface 
   *      that has to be bound. If <code>null</code> the client component is 
   *      assumed to be the component this interface belongs.
   * @param clientItfName the name of the interface at the client side of the
   *      binding. If the given <code>clientComponent</code> is a sub component;
   *      this name must refer to a client interface. If the given 
   *      <code>clientComponent</code> refers to the component this interface 
   *      belongs; this name must refer to a server interface.
   * @param serverComponent the component that contains the server interface 
   *      that has to be bound. If <code>null</code> the server component is 
   *      assumed to be the component this interface belongs.
   * @param serverItfName the name of the interface at the server side of the
   *      binding. If the given <code>serverComponent</code> is a sub component;
   *      this name must refer to a server interface. If the given 
   *      <code>serverComponent</code> refers to the component this interface 
   *      belongs; this name must refer to a client interface.
   * @return <code>0</code> if the binding has been added correctly. 
   *      {@link ErrorConst#ILLEGAL_BINDING} if the binding cannot be created. 
   *      {@link ErrorConst#NO_SUCH_SUB_COMPONENT} if the
   *      <code>clientComponent</code> or the <code>serverComponent</code> is
   *      neither a sub component nor the component this interface belongs.
   *      {@link ErrorConst#ILLEGAL_LIFE_CYCLE} if this component has a 
   *      {@link LifeCycleController} interface, but it is not in an appropriate
   *      state to perform this operation.
   *      {@link ErrorConst#OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int addFcSubBinding(in Component clientComponent, 
      const in string clientItfName, in Component serverComponent, 
      const in string serverItfName);

  /**
   * Removes a binding inside this component.
   *
   * @param clientComponent the component that contains the client interface 
   *      that has to be unbound. If <code>null</code> the client component is 
   *      assumed to be the component this interface belongs.
   * @param clientItfName the name of the interface that has to be unbound. 
   *      If the given <code>clientComponent</code> is a sub component;
   *      this name must refer to a client interface. If the given 
   *      <code>clientComponent</code> refers to the component this interface 
   *      belongs; this name must refer to a server interface.
   * @return <code>0</code> if the binding has been removed correctly. 
   *      {@link ErrorConst#ILLEGAL_BINDING} if the binding cannot be removed. 
   *      {@link ErrorConst#NO_SUCH_SUB_COMPONENT} if the given
   *      <code>clientComponent</code> is neither a sub component nor the 
   *      component this interface belongs.
   *      {@link ErrorConst#ILLEGAL_LIFE_CYCLE} if this component has a 
   *      {@link LifeCycleController} interface, but it is not in an appropriate
   *      state to perform this operation.
   *      {@link ErrorConst#OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int removeFcSubBinding(in Component clientComponent, 
      const in string clientItfName);   
}