Commit b0a61780 authored by Carlos Eduardo Lara Augusto's avatar Carlos Eduardo Lara Augusto
Browse files

[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
parent 67fe257b
......@@ -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!!
* 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.
*
* 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.
* The user is responsible for reactivating the facets when deemed
* appropriate.
*
* @param context Instncia do componente.
*
* @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) {
......
......@@ -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;
......
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() {
......
......@@ -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() {
......
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() {
......