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; ...@@ -13,6 +13,17 @@ import org.omg.PortableServer.Servant;
import scs.core.exception.SCSException; 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 { public class ComponentContext {
private ORB orb; private ORB orb;
private POA poa; private POA poa;
...@@ -21,20 +32,34 @@ public class ComponentContext { ...@@ -21,20 +32,34 @@ public class ComponentContext {
private Map<String, Receptacle> receptacles; 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; 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; 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 * The returned instance of this class is considered a new SCS component
* @throws SCSException * 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 { public ComponentContext(ORB orb, POA poa, ComponentId id) throws SCSException {
if (orb == null) { if (orb == null) {
...@@ -94,8 +119,8 @@ public class ComponentContext { ...@@ -94,8 +119,8 @@ public class ComponentContext {
private void deactivateFacet(Facet facet) throws SCSException { private void deactivateFacet(Facet facet) throws SCSException {
if (facet != null) { if (facet != null) {
try { try {
poa poa.deactivate_object(poa
.deactivate_object(poa.reference_to_id(facet.getDescription().facet_ref)); .reference_to_id(facet.getDescription().facet_ref));
} }
catch (UserException e) { catch (UserException e) {
throw new SCSException(e); throw new SCSException(e);
...@@ -103,10 +128,32 @@ public class ComponentContext { ...@@ -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() { public ComponentId getComponentId() {
return componentId; 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) public void putFacet(String name, String interface_name, Servant servant)
throws SCSException { throws SCSException {
checkForGetComponentMethod(servant); checkForGetComponentMethod(servant);
...@@ -128,6 +175,17 @@ public class ComponentContext { ...@@ -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, public void putReceptacle(String name, String interface_name,
boolean is_multiplex) { boolean is_multiplex) {
Receptacle receptacle = Receptacle receptacle =
...@@ -140,6 +198,13 @@ public class ComponentContext { ...@@ -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 { public void removeFacet(String name) throws SCSException {
Facet facet = facets.get(name); Facet facet = facets.get(name);
deactivateFacet(facet); deactivateFacet(facet);
...@@ -147,6 +212,11 @@ public class ComponentContext { ...@@ -147,6 +212,11 @@ public class ComponentContext {
//TODO: logar que uma faceta foi removida //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) { public void removeReceptacle(String name) {
if (receptacles.containsKey(name)) { if (receptacles.containsKey(name)) {
Receptacle receptacle = receptacles.remove(name); Receptacle receptacle = receptacles.remove(name);
...@@ -156,6 +226,13 @@ public class ComponentContext { ...@@ -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() { public Map<String, SCSException> activateComponent() {
Map<String, SCSException> errMsgs = new HashMap<String, SCSException>(); Map<String, SCSException> errMsgs = new HashMap<String, SCSException>();
for (Facet facet : facets.values()) { for (Facet facet : facets.values()) {
...@@ -171,23 +248,23 @@ public class ComponentContext { ...@@ -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
* Desativa todas as facetas do componente. As referncias facet_ref continuam * call, to maintain access to the Java object.
* no-nulas aps a chamada, para manter o acesso ao objeto Java. O usurio
* fica responsvel por reativar as facetas quando considerar apropriado.
* *
* @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 * @return A map indicating the facets that could not be deactivated. The map
* erro(valores) das facetas que no puderam ser desativadas. * uses the facet name as an identifier and the catched exception as
* the value.
*/ */
public Map<String, SCSException> deactivateComponent() { public Map<String, SCSException> deactivateComponent() {
Map<String, SCSException> errMsgs = new HashMap<String, SCSException>(); Map<String, SCSException> errMsgs = new HashMap<String, SCSException>();
for (Facet facet : facets.values()) { for (Facet facet : facets.values()) {
try { try {
poa poa.deactivate_object(poa
.deactivate_object(poa.reference_to_id(facet.getDescription().facet_ref)); .reference_to_id(facet.getDescription().facet_ref));
} }
catch (UserException e) { catch (UserException e) {
//TODO: logar erro ao desativar faceta como warn //TODO: logar erro ao desativar faceta como warn
...@@ -197,10 +274,22 @@ public class ComponentContext { ...@@ -197,10 +274,22 @@ public class ComponentContext {
return errMsgs; return errMsgs;
} }
/**
* Provides metadata about the component's facets.
*
* @return An unmodifiable collection with the facet metadata.
*/
public Collection<Facet> getFacets() { public Collection<Facet> getFacets() {
return Collections.unmodifiableCollection(facets.values()); 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) { public Facet getFacetByName(String name) {
if (name == null) { if (name == null) {
throw new IllegalArgumentException("The facet's name can't be null"); throw new IllegalArgumentException("The facet's name can't be null");
...@@ -208,14 +297,31 @@ public class ComponentContext { ...@@ -208,14 +297,31 @@ public class ComponentContext {
return facets.get(name); return facets.get(name);
} }
/**
* Provides metadata about the component's receptacles.
*
* @return An unmodifiable collection with the receptacle metadata.
*/
public Collection<Receptacle> getReceptacles() { public Collection<Receptacle> getReceptacles() {
return Collections.unmodifiableCollection(receptacles.values()); 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) { public Receptacle getReceptacleByName(String name) {
return receptacles.get(name); return receptacles.get(name);
} }
/**
* Provides a direct reference to the IComponent facet.
*
* @return The IComponent facet.
*/
public IComponent getIComponent() { public IComponent getIComponent() {
Facet facet = facets.get(IComponent.class.getSimpleName()); Facet facet = facets.get(IComponent.class.getSimpleName());
if (facet != null) { if (facet != null) {
......
...@@ -3,18 +3,32 @@ package scs.core; ...@@ -3,18 +3,32 @@ package scs.core;
import org.omg.PortableServer.Servant; 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 * It doesn't maintain a FacetDescription directly because the FacetDescription
* pblicos. O getter forneceria a classe que poderia ter seus dados * is an automatically generated class. The generated code sets all of its
* modificados. * fields as public but these fields should not be manipulated freely.
*
* @author cadu
*
*/ */
public final class Facet { public final class Facet {
/**
* The name of the facet, which acts as its identifier within the component.
*/
private String name; private String name;
/**
* The IDL interface that this facet represents.
*/
private String interfaceName; private String interfaceName;
/**
* The CORBA object.
*/
private org.omg.CORBA.Object reference; private org.omg.CORBA.Object reference;
/**
* The Servant instance that implements the interface.
*/
private Servant servant; private Servant servant;
Facet(String name, String interfaceName, org.omg.CORBA.Object referece, Facet(String name, String interfaceName, org.omg.CORBA.Object referece,
...@@ -39,26 +53,46 @@ public final class Facet { ...@@ -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() { public FacetDescription getDescription() {
return new FacetDescription(name, interfaceName, reference); return new FacetDescription(name, interfaceName, reference);
} }
/**
* Provides the name of this facet.
*
* @return The facet name.
*/
public String getName() { public String getName() {
return name; return name;
} }
/**
* Provides the interface of this facet.
*
* @return The facet interface.
*/
public String getInterfaceName() { public String getInterfaceName() {
return interfaceName; return interfaceName;
} }
/**
* Provides the CORBA reference of this facet, as a CORBA object.
*
* @return The CORBA object.
*/
public org.omg.CORBA.Object getReference() { public org.omg.CORBA.Object getReference() {
return reference; 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() { public Servant getServant() {
return servant; return servant;
......
package scs.core; package scs.core;
/** /**
* Servant da interface IDL {@link IComponent}. Implementa as características * This class is the basic implementation of the IDL interface
* comuns a todos IComponent. * {@link IComponent}. The IComponent interface is the CORBA representation of a
* * SCS component.
* @author Carlos Eduardo
* @author (comentários) Amadeu A. Barbosa Jr
*/ */
public class IComponentServant extends IComponentPOA { public class IComponentServant extends IComponentPOA {
/** /**
* Referência para o contexto do componente. O contexto provém facilidades * Reference to the context of this facet, i.e., the local representation of
* para acesso a dados compartilhados entre as diversas facetas * its component.
*/ */
protected ComponentContext myComponent; protected ComponentContext myComponent;
/** /**
* Construtor padrão usado pela infra-estrutura do SCS durante a instanciação * Primary constructor.
* automática das facetas
* *
* @param myComponent Contexto do componente contendo as descrições das portas * @param myComponent The component that owns this facet instance.
* (facetas e receptáculos) e métodos de ajuda que facilitam o uso da
* infra-estrutura
*/ */
public IComponentServant(ComponentContext myComponent) { public IComponentServant(ComponentContext myComponent) {
this.myComponent = 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 * @param facet_interface The facet interface.
* @return Objeto CORBA que implementa a faceta * @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) * @see scs.core.IComponentOperations#getFacet(java.lang.String)
*/ */
public org.omg.CORBA.Object getFacet(String facet_interface) { public org.omg.CORBA.Object getFacet(String facet_interface) {
...@@ -44,10 +44,13 @@ public class IComponentServant extends IComponentPOA { ...@@ -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 * @param facetName The facet name.
* @return Objeto CORBA que implementa a faceta * @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) * @see scs.core.IComponentOperations#getFacetByName(java.lang.String)
*/ */
public org.omg.CORBA.Object getFacetByName(String facetName) { public org.omg.CORBA.Object getFacetByName(String facetName) {
...@@ -59,8 +62,8 @@ public class IComponentServant extends IComponentPOA { ...@@ -59,8 +62,8 @@ public class IComponentServant extends IComponentPOA {
} }
/** /**
* Implementação vazia que pode ser sobrecarregada para permitir algum * Empty implementation. This method should be overridden by the user if
* procedimento específico na inicialização do IComponent * component initialization is required.
* *
* @see scs.core.IComponentOperations#startup() * @see scs.core.IComponentOperations#startup()
*/ */
...@@ -68,8 +71,8 @@ public class IComponentServant extends IComponentPOA { ...@@ -68,8 +71,8 @@ public class IComponentServant extends IComponentPOA {
} }
/** /**
* Implementação vazia que pode ser sobrecarregada para permitir algum * Empty implementation. This method should be overridden by the user if
* procedimento específico na finalização do IComponent * component finalization is required.
* *
* @see scs.core.IComponentOperations#shutdown() * @see scs.core.IComponentOperations#shutdown()
*/ */
...@@ -77,16 +80,19 @@ public class IComponentServant extends IComponentPOA { ...@@ -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() { public ComponentId getComponentId() {
return myComponent.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 @Override
public org.omg.CORBA.Object _get_component() { public org.omg.CORBA.Object _get_component() {
......
...@@ -4,35 +4,31 @@ import java.util.Collection; ...@@ -4,35 +4,31 @@ import java.util.Collection;
import java.util.Iterator; import java.util.Iterator;
/** /**
* Servant da interface IDL {@link IMetaInterface}. Implementa as * This class is the basic implementation of the IDL interface
* caractersticas comuns a todos IMetaInterface. * {@link IMetaInterface}. The IMetaInterface interface provides access to the
* * component's metadata, acting as an introspection facet.
* @author Eduardo Fonseca/Luiz Marques
*
*/ */
public class IMetaInterfaceServant extends scs.core.IMetaInterfacePOA { public class IMetaInterfaceServant extends scs.core.IMetaInterfacePOA {
/** /**
* Referncia para o contexto do componente. O contexto provm facilidades * Reference to the context of this facet, i.e., the local representation of
* para acesso a dados compartilhados entre as diversas facetas * its component.
*/ */
protected ComponentContext myComponent; protected ComponentContext myComponent;
/** /**
* Construtor padro usado pela infra-estrutura do SCS durante a instanciao * Primary constructor.
* automtica das facetas
* *
* @param myComponent Contexto do componente contendo as descries das portas * @param myComponent The component that owns this facet instance.
* (facetas e receptculos) e mtodos de ajuda que facilitam o uso da
* infra-estrutura
*/ */