[SCS-209]

Comentários revisados e em inglês para o SDK Java do SCS 1.3.



git-svn-id: https://subversion.tecgraf.puc-rio.br/engdist/scs/core/java/trunk@116420 ae0415b3-e90b-0410-900d-d0be9363c56b

src/scs/core/ComponentContext.java

@@ -13,6 +13,17 @@ import org.omg.PortableServer.Servant;
 
 import scs.core.exception.SCSException;
 
+/**
+ * This class is the local representation of a SCS component. Its concept
+ * doesn't exist in the CORBA environment. As such, an instance of this class is
+ * considered a local instance of a component and gathers all of its facets,
+ * receptacles and meta-data. It also holds references to the ORB and POA used
+ * to create and activate its facets.
+ * 
+ * Specifically in Java, this class is also responsible for generating
+ * connection id's for receptacles.
+ * 
+ */
 public class ComponentContext {
   private ORB orb;
   private POA poa;
@@ -21,20 +32,34 @@ public class ComponentContext {
   private Map<String, Receptacle> receptacles;
 
   /**
-   * Contador para gerar o ID da conexao (por instancia de componente)
+   * Counter used to generate connection id's. Connection id's are valid per
+   * component, not per receptacle.
    */
   private int currentConnectionId = 0;
 
   /**
-   * Limite de conexes por componente
+   * Limit of concurrent connections, per component. This'll probably be removed
+   * in the next version!
    */
   public final int CONNECTION_LIMIT = 100;
 
   /**
-   * Method that serves as a factory for the component.
+   * Primary constructor. The returned component instance will always have the
+   * three basic facets (IComponent, IReceptacles, IMetaInterface) instantiated.
+   * If the user wishes to use his own implementation of one of these facets,
+   * it's possible to replace them via the putFacet method. Other facets and
+   * receptacles can also be added.
    * 
-   * @return A new component
-   * @throws SCSException
+   * The returned instance of this class is considered a new SCS component
+   * instance.
+   * 
+   * @param orb The ORB to be used when creating this component instance's
+   *        facets.
+   * @param poa The POA to register this component instance's facets.
+   * @param id The type of this component.
+   * 
+   * @throws SCSException If any error occurs. The exception shall contain
+   *         another, more specific exception.
    */
   public ComponentContext(ORB orb, POA poa, ComponentId id) throws SCSException {
     if (orb == null) {
@@ -94,8 +119,8 @@ public class ComponentContext {
   private void deactivateFacet(Facet facet) throws SCSException {
     if (facet != null) {
       try {
-        poa
-          .deactivate_object(poa.reference_to_id(facet.getDescription().facet_ref));
+        poa.deactivate_object(poa
+          .reference_to_id(facet.getDescription().facet_ref));
       }
       catch (UserException e) {
         throw new SCSException(e);
@@ -103,10 +128,32 @@ public class ComponentContext {
     }
   }
 
+  /**
+   * Provides the ComponentId of this component instance. ComponentId's aren't
+   * instance identifiers; they specify a component's name, version and platform
+   * specification.
+   * 
+   * @return The component's ComponentId
+   */
   public ComponentId getComponentId() {
     return componentId;
   }
 
+  /**
+   * Adds a new facet to the component instance. This method activates the facet
+   * with the POA associated to the component. Also, it checks for the existence
+   * of the _get_component() method. If it's not implemented, a warning will be
+   * logged.
+   * 
+   * If the facet name already exists, the old facet will be replaced and
+   * deactivated within the component's POA.
+   * 
+   * @param name The facet's name. This acts as the facet identifier within the
+   *        component.
+   * @param interface_name The facet's IDL interface.
+   * @param servant The facet implementation, not yet activated within the POA.
+   * @throws SCSException If an UserException is catched.
+   */
   public void putFacet(String name, String interface_name, Servant servant)
     throws SCSException {
     checkForGetComponentMethod(servant);
@@ -128,6 +175,17 @@ public class ComponentContext {
     }
   }
 
+  /**
+   * Adds a new receptacle to the component instance.
+   * 
+   * If the receptacle name already exists, the old receptacle will be replaced.
+   * 
+   * @param name The receptacle's name. This acts as the receptacle identifier
+   *        within the component.
+   * @param interface_name The receptacle's IDL interface.
+   * @param is_multiplex True if the receptacle accepts more than one
+   *        connection, false otherwise.
+   */
   public void putReceptacle(String name, String interface_name,
     boolean is_multiplex) {
     Receptacle receptacle =
@@ -140,6 +198,13 @@ public class ComponentContext {
     }
   }
 
+  /**
+   * Removes a facet from the component. The facet is deactivated within the
+   * component's POA before being removed.
+   * 
+   * @param name The name of the facet to be removed.
+   * @throws SCSException If an UserException is catched.
+   */
   public void removeFacet(String name) throws SCSException {
     Facet facet = facets.get(name);
     deactivateFacet(facet);
@@ -147,6 +212,11 @@ public class ComponentContext {
     //TODO: logar que uma faceta foi removida
   }
 
+  /**
+   * Removes a receptacle from the component.
+   * 
+   * @param name The name of the receptacle to be removed.
+   */
   public void removeReceptacle(String name) {
     if (receptacles.containsKey(name)) {
       Receptacle receptacle = receptacles.remove(name);
@@ -156,6 +226,13 @@ public class ComponentContext {
     }
   }
 
+  /**
+   * Activates all of the component's facets.
+   * 
+   * @return A map indicating the facets that could not be activated. The map
+   *         uses the facet name as an identifier and the catched exception as
+   *         the value.
+   */
   public Map<String, SCSException> activateComponent() {
     Map<String, SCSException> errMsgs = new HashMap<String, SCSException>();
     for (Facet facet : facets.values()) {
@@ -171,23 +248,23 @@ public class ComponentContext {
   }
 
   /**
-   * TODO: descricao nao esta mais correta!!
-   * 
-   * Desativa todas as facetas do componente. As referncias facet_ref continuam
-   * no-nulas aps a chamada, para manter o acesso ao objeto Java. O usurio
-   * fica responsvel por reativar as facetas quando considerar apropriado.
+   * Deactivates all of the component's facets within the POA. The facet_ref
+   * references (from the FacetDescription metadata) remain non-null after the
+   * call, to maintain access to the Java object.
    * 
-   * @param context Instncia do componente.
+   * The user is responsible for reactivating the facets when deemed
+   * appropriate.
    * 
-   * @return Mapa contendo os nomes das facetas(chaves) e as mensagens de
-   *         erro(valores) das facetas que no puderam ser desativadas.
+   * @return A map indicating the facets that could not be deactivated. The map
+   *         uses the facet name as an identifier and the catched exception as
+   *         the value.
    */
   public Map<String, SCSException> deactivateComponent() {
     Map<String, SCSException> errMsgs = new HashMap<String, SCSException>();
     for (Facet facet : facets.values()) {
       try {
-        poa
-          .deactivate_object(poa.reference_to_id(facet.getDescription().facet_ref));
+        poa.deactivate_object(poa
+          .reference_to_id(facet.getDescription().facet_ref));
       }
       catch (UserException e) {
         //TODO: logar erro ao desativar faceta como warn
@@ -197,10 +274,22 @@ public class ComponentContext {
     return errMsgs;
   }
 
+  /**
+   * Provides metadata about the component's facets.
+   * 
+   * @return An unmodifiable collection with the facet metadata.
+   */
   public Collection<Facet> getFacets() {
     return Collections.unmodifiableCollection(facets.values());
   }
 
+  /**
+   * Provides metadata about a specific facet.
+   * 
+   * @param name The name of the facet.
+   * 
+   * @return The facet metadata.
+   */
   public Facet getFacetByName(String name) {
     if (name == null) {
       throw new IllegalArgumentException("The facet's name can't be null");
@@ -208,14 +297,31 @@ public class ComponentContext {
     return facets.get(name);
   }
 
+  /**
+   * Provides metadata about the component's receptacles.
+   * 
+   * @return An unmodifiable collection with the receptacle metadata.
+   */
   public Collection<Receptacle> getReceptacles() {
     return Collections.unmodifiableCollection(receptacles.values());
   }
 
+  /**
+   * Provides metadata about a specific receptacle.
+   * 
+   * @param name The name of the receptacle.
+   * 
+   * @return The receptacle metadata.
+   */
   public Receptacle getReceptacleByName(String name) {
     return receptacles.get(name);
   }
 
+  /**
+   * Provides a direct reference to the IComponent facet.
+   * 
+   * @return The IComponent facet.
+   */
   public IComponent getIComponent() {
     Facet facet = facets.get(IComponent.class.getSimpleName());
     if (facet != null) {

src/scs/core/Facet.java

@@ -3,18 +3,32 @@ package scs.core;
 import org.omg.PortableServer.Servant;
 
 /**
+ * This class holds all the metadata pertinent to a facet, and represents it
+ * locally.
  * 
- * No colocamos um campo FacetDescription direto pois a classe tem os campos
- * pblicos. O getter forneceria a classe que poderia ter seus dados
- * modificados.
- * 
- * @author cadu
- * 
+ * It doesn't maintain a FacetDescription directly because the FacetDescription
+ * is an automatically generated class. The generated code sets all of its
+ * fields as public but these fields should not be manipulated freely.
  */
 public final class Facet {
+  /**
+   * The name of the facet, which acts as its identifier within the component.
+   */
   private String name;
+
+  /**
+   * The IDL interface that this facet represents.
+   */
   private String interfaceName;
+
+  /**
+   * The CORBA object.
+   */
   private org.omg.CORBA.Object reference;
+
+  /**
+   * The Servant instance that implements the interface.
+   */
   private Servant servant;
 
   Facet(String name, String interfaceName, org.omg.CORBA.Object referece,
@@ -39,26 +53,46 @@ public final class Facet {
   }
 
   /**
-   * @return FacetDescription
+   * Provides the IDL structure FacetDescription of this facet.
+   * 
+   * @return FacetDescription The description.
    */
   public FacetDescription getDescription() {
     return new FacetDescription(name, interfaceName, reference);
   }
 
+  /**
+   * Provides the name of this facet.
+   * 
+   * @return The facet name.
+   */
   public String getName() {
     return name;
   }
 
+  /**
+   * Provides the interface of this facet.
+   * 
+   * @return The facet interface.
+   */
   public String getInterfaceName() {
     return interfaceName;
   }
 
+  /**
+   * Provides the CORBA reference of this facet, as a CORBA object.
+   * 
+   * @return The CORBA object.
+   */
   public org.omg.CORBA.Object getReference() {
     return reference;
   }
 
   /**
-   * @return Servant
+   * Provides the Servant instance of this facet, which is the Java class that
+   * implements the facet interface.
+   * 
+   * @return Servant The Java Servant.
    */
   public Servant getServant() {
     return servant;

src/scs/core/IComponentServant.java

 package scs.core;
 
 /**
- * Servant da interface IDL {@link IComponent}. Implementa as características
- * comuns a todos IComponent.
- * 
- * @author Carlos Eduardo
- * @author (comentários) Amadeu A. Barbosa Jr
+ * This class is the basic implementation of the IDL interface
+ * {@link IComponent}. The IComponent interface is the CORBA representation of a
+ * SCS component.
  */
 public class IComponentServant extends IComponentPOA {
 
   /**
-   * Referência para o contexto do componente. O contexto provém facilidades
-   * para acesso a dados compartilhados entre as diversas facetas
+   * Reference to the context of this facet, i.e., the local representation of
+   * its component.
    */
   protected ComponentContext myComponent;
 
   /**
-   * Construtor padrão usado pela infra-estrutura do SCS durante a instanciação
-   * automática das facetas
+   * Primary constructor.
    * 
-   * @param myComponent Contexto do componente contendo as descrições das portas
-   *        (facetas e receptáculos) e métodos de ajuda que facilitam o uso da
-   *        infra-estrutura
+   * @param myComponent The component that owns this facet instance.
    */
   public IComponentServant(ComponentContext myComponent) {
     this.myComponent = myComponent;
   }
 
   /**
-   * Obtém o objeto CORBA a partir do nome da interface IDL da faceta
+   * Provides the CORBA reference to one of the component's facets, by its
+   * interface. Since there can be more than one facet with the same interface,
+   * there's no guarantee on which one of these will be returned.
    * 
-   * @param facet_interface String da interface CORBA implementada pela faceta
-   * @return Objeto CORBA que implementa a faceta
+   * @param facet_interface The facet interface.
+   * @return The CORBA object that represents the facet. If there's more than
+   *         one facet with the specified interface, any one of them may be
+   *         returned. If there's no facet with the specified interface, null is
+   *         returned.
    * @see scs.core.IComponentOperations#getFacet(java.lang.String)
    */
   public org.omg.CORBA.Object getFacet(String facet_interface) {
@@ -44,10 +44,13 @@ public class IComponentServant extends IComponentPOA {
   }
 
   /**
-   * Obtém o objeto CORBA a partir do nome fictício da faceta
+   * Provides the CORBA reference to one of the component's facets, by its name.
+   * There cannot be more than one facet with the same name, so there's only one
+   * possible return value.
    * 
-   * @param facetName Nome fictício da faceta
-   * @return Objeto CORBA que implementa a faceta
+   * @param facetName The facet name.
+   * @return The CORBA object that represents the facet. If there's no facet
+   *         with the specified interface, null is returned.
    * @see scs.core.IComponentOperations#getFacetByName(java.lang.String)
    */
   public org.omg.CORBA.Object getFacetByName(String facetName) {
@@ -59,8 +62,8 @@ public class IComponentServant extends IComponentPOA {
   }
 
   /**
-   * Implementação vazia que pode ser sobrecarregada para permitir algum
-   * procedimento específico na inicialização do IComponent
+   * Empty implementation. This method should be overridden by the user if
+   * component initialization is required.
    * 
    * @see scs.core.IComponentOperations#startup()
    */
@@ -68,8 +71,8 @@ public class IComponentServant extends IComponentPOA {
   }
 
   /**
-   * Implementação vazia que pode ser sobrecarregada para permitir algum
-   * procedimento específico na finalização do IComponent
+   * Empty implementation. This method should be overridden by the user if
+   * component finalization is required.
    * 
    * @see scs.core.IComponentOperations#shutdown()
    */
@@ -77,16 +80,19 @@ public class IComponentServant extends IComponentPOA {
   }
 
   /**
-   * Obtém o identificador do componente
+   * Provides the component's ComponentId. ComponentId's aren't instance
+   * identifiers; they specify a component's name, version and platform
+   * specification.
    * 
-   * @return Identificador do componente
+   * @return The ComponentId.
    */
   public ComponentId getComponentId() {
     return myComponent.getComponentId();
   }
 
   /**
-   * Retorna a referência para a faceta IComponent. Específico do JACORB.
+   * Provides the reference to the most basic facet of the component,
+   * IComponent.
    */
   @Override
   public org.omg.CORBA.Object _get_component() {

src/scs/core/IMetaInterfaceServant.java

@@ -4,35 +4,31 @@ import java.util.Collection;
 import java.util.Iterator;
 
 /**
- * Servant da interface IDL {@link IMetaInterface}. Implementa as
- * caractersticas comuns a todos IMetaInterface.
- * 
- * @author Eduardo Fonseca/Luiz Marques
- * 
+ * This class is the basic implementation of the IDL interface
+ * {@link IMetaInterface}. The IMetaInterface interface provides access to the
+ * component's metadata, acting as an introspection facet.
  */
 public class IMetaInterfaceServant extends scs.core.IMetaInterfacePOA {
 
   /**
-   * Referncia para o contexto do componente. O contexto provm facilidades
-   * para acesso a dados compartilhados entre as diversas facetas
+   * Reference to the context of this facet, i.e., the local representation of
+   * its component.
    */
   protected ComponentContext myComponent;
 
   /**
-   * Construtor padro usado pela infra-estrutura do SCS durante a instanciao
-   * automtica das facetas
+   * Primary constructor.
    * 
-   * @param myComponent Contexto do componente contendo as descries das portas
-   *        (facetas e receptculos) e mtodos de ajuda que facilitam o uso da
-   *        infra-estrutura
+   * @param myComponent The component that owns this facet instance.
    */
   public IMetaInterfaceServant(ComponentContext myComponent) {
     this.myComponent = myComponent;
   }
 
   /**
-   * Listagem das descries de facetas
+   * Provides CORBA references and metadata of all of the component's facets.
    * 
+   * @return An array with the facets metadata.
    * @see IMetaInterfaceOperations#getFacets()
    */
   public FacetDescription[] getFacets() {
@@ -46,9 +42,12 @@ public class IMetaInterfaceServant extends scs.core.IMetaInterfacePOA {
   }
 
   /**
-   * Busca de descries de facetas a partir de uma lista de nomes fictcios
+   * Provides CORBA references and metadata of some of the component's facets,
+   * specified by their names.
    * 
-   * @see IMetaInterfaceOperations#getFacetsByName(String[])
+   * @param names The names of the desired facets.
+   * @return An array with the specified facets metadata.
+   * @see IMetaInterfaceOperations#getFacetsByName(String[] names)
    */
   public FacetDescription[] getFacetsByName(String[] names) throws InvalidName {
     FacetDescription[] facets = new FacetDescription[names.length];
@@ -63,8 +62,9 @@ public class IMetaInterfaceServant extends scs.core.IMetaInterfacePOA {
   }
 
   /**
-   * Listagem de todas descries de receptculos
+   * Provides metadata of all of the component's receptacles.
    * 
+   * @return An array with the receptacles metadata.
    * @see IMetaInterfaceOperations#getReceptacles()
    */
   public ReceptacleDescription[] getReceptacles() {
@@ -79,10 +79,12 @@ public class IMetaInterfaceServant extends scs.core.IMetaInterfacePOA {
   }
 
   /**
-   * Busca de descries de receptculos a partir de uma lista de nomes
-   * fictcios
+   * Provides metadata of some of the component's receptacles, specified by
+   * their names.
    * 
-   * @see IMetaInterfaceOperations#getReceptaclesByName(String[])
+   * @param names The names of the desired receptacles.
+   * @return An array with the specified receptacles metadata.
+   * @see IMetaInterfaceOperations#getReceptaclesByName(String[] names)
    */
   public ReceptacleDescription[] getReceptaclesByName(String[] names)
     throws InvalidName {
@@ -99,7 +101,8 @@ public class IMetaInterfaceServant extends scs.core.IMetaInterfacePOA {
   }
 
   /**
-   * Retorna a referncia para a faceta IComponent. Especfico do JACORB.
+   * Provides the reference to the most basic facet of the component,
+   * IComponent.
    */
   @Override
   public org.omg.CORBA.Object _get_component() {

src/scs/core/IReceptaclesServant.java

 package scs.core;
 
 /**
- * Servant da interface IDL {@link IReceptacles}. Implementa as características
- * comuns a todos IReceptacles.
+ * This class is the basic implementation of the IDL interface
+ * {@link IReceptacles}. The IReceptacle interface provides access to and
+ * manipulation of the component's receptacles.
  */
 public class IReceptaclesServant extends IReceptaclesPOA {
 
   /**
-   * Referência para o contexto do componente. O contexto provém facilidades
-   * para acesso a dados compartilhados entre as diversas facetas
+   * Reference to the context of this facet, i.e., the local representation of
+   * its component.
    */
   private ComponentContext myComponent;
 
   /**
-   * Construtor padrão que recebe o contexto do componente.
+   * Primary constructor.
    * 
-   * @param myComponent Contexto do componente contendo as descrições das portas
-   *        (facetas e receptáculos) e métodos de ajuda que facilitam o uso da
-   *        infra-estrutura
+   * @param myComponent The component that owns this facet instance.
    */
   public IReceptaclesServant(ComponentContext myComponent) {
     this.myComponent = myComponent;
   }
 
   /**
-   * Método para conectar um objeto provedor de serviço no receptáculo
-   * 
-   * @param receptacle Nome fictício do receptáculo
-   * @param obj Referência para o objeto CORBA que implementa o serviço
-   * @return Inteiro identificador da conexão
+   * Connects a remote facet to a receptacle. The facet must implement the
+   * interface specified by the receptacle.
    * 
+   * @param receptacle The receptacle name.
+   * @param obj The remote facet reference.
+   * @return The connection identifier. It's valid for the entire component, not
+   *         for a specific receptacle.
+   * @throws InvalidName If there's no receptacle with the specified name.
+   * @throws InvalidConnection If the facet object does not implement the
+   *         receptacle's specified interface.
+   * @throws AlreadyConnected If the receptacle supports only one connection and
+   *         is already connected.
+   * @throws ExceededConnectionLimit If the receptacle is multiplex and the
+   *         maximum number of connections was already reached.
    * @see IReceptaclesOperations#connect(String, org.omg.CORBA.Object)
    */
   public synchronized int connect(String receptacle, org.omg.CORBA.Object obj)
@@ -43,9 +50,13 @@ public class IReceptaclesServant extends IReceptaclesPOA {
   }
 
   /**
-   * Método para desconectar um provedor de serviço do receptáculo
+   * Disconnects a remote facet from a receptacle. There's no need to specify
+   * the receptacle.
    * 
-   * @param id Inteiro identificador da conexão
+   * @param id The connection identifier.
+   * @throws InvalidConnection If the connection identifier is invalid, i.e.,
+   *         less than or equal to zero.
+   * @throws NoConnection If the provided connection identifier does not exist.
    */
   public synchronized void disconnect(int id) throws InvalidConnection,
     NoConnection {
@@ -66,10 +77,11 @@ public class IReceptaclesServant extends IReceptaclesPOA {
   }
 
   /**
-   * Listagem de descrições da conexões ativas
+   * Provides metadata about all connections of a specified receptacle.
    * 
-   * @param receptacle Nome fictício do receptáculo
-   * @return Vetor com as descrições das conexões válidas para o receptáculo
+   * @param receptacle The receptacle name.
+   * @return An array with the connections metadata.
+   * @throws InvalidName If the specified receptacle does not exist.
    * @see IReceptaclesOperations#getConnections(String)
    */
   public synchronized ConnectionDescription[] getConnections(String receptacle)
@@ -81,7 +93,8 @@ public class IReceptaclesServant extends IReceptaclesPOA {
   }
 
   /**
-   * Retorna a referência para a faceta IComponent. Específico do JACORB.
+   * Provides the reference to the most basic facet of the component,
+   * IComponent.
    */
   @Override
   public org.omg.CORBA.Object _get_component() {