Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

alma::acs::container::ComponentHelper Class Reference

List of all members.

Public Member Functions

 ComponentHelper (Logger containerLogger)

Protected Member Functions

final Logger getComponentLogger ()
final synchronized ComponentLifecycle getComponentImpl () throws AcsJComponentCreationEx, AcsJJavaComponentHelperEx
abstract ComponentLifecycle _createComponentImpl () throws AcsJComponentCreationEx
abstract Class<?extends Servant > _getPOATieClass ()
abstract Class<?extends ACSComponentOperations_getOperationsInterface ()
Class<?> getInternalInterface () throws AcsJJavaComponentHelperEx
Object _getInterfaceTranslator (Object defaultInterfaceTranslator) throws AcsJJavaComponentHelperEx
String[] _getComponentMethodsExcludedFromInvocationLogging ()
boolean requiresOrbCentralLogSuppression ()

Protected Attributes

String componentInstanceName

Package Functions

final void setComponentInstanceName (String name)
final Class<?extends Servant > getPOATieClass () throws AcsJJavaComponentHelperEx
final Class<?extends ACSComponentOperationsgetOperationsInterface () throws AcsJJavaComponentHelperEx
final Object getInterfaceTranslator () throws AcsJJavaComponentHelperEx
final String[] getComponentMethodsExcludedFromInvocationLogging ()

Private Attributes

ComponentLifecycle m_componentImpl
final Logger m_containerLogger

Detailed Description

Base class for component helper classes that must be provided by the component developers (for example by copying the template file that gets generated with the COMPONENT_HELPERS=on Makefile setting).

The method implementations in this class perform checks on the data returned from the subclass methods (framework-style design). In that sense, ComponentHelper is part of the container, whereas its subclass belongs to the component.

The methods that return a Class object should be implemented like return XxxPOATie.class; so that the absence of this class can be discovered at compile time. (Therefore don't use classForName which evades compile time checking.)

Author:
hsommer


Constructor & Destructor Documentation

alma::acs::container::ComponentHelper::ComponentHelper Logger  containerLogger  )  [inline]
 

Subclasses must override and call this constructor ("<code>super(containerLogger)</code>").

Parameters:
containerLogger logger used by this base class.


Member Function Documentation

abstract ComponentLifecycle alma::acs::container::ComponentHelper::_createComponentImpl  )  throws AcsJComponentCreationEx [protected, pure virtual]
 

Method _createComponentImpl to be provided by subclasses. Must return the same object that also implements the functional component interface.

Returns:
ComponentLifecycle The component impl class that implements the ComponentLifecycle interface.
Exceptions:
AcsJComponentCreationEx if the component implementation class could not be instantiated

String [] alma::acs::container::ComponentHelper::_getComponentMethodsExcludedFromInvocationLogging  )  [inline, protected]
 

Tells the container to not automatically log calls to certain component interface methods. This method may be overridden by helper subclasses, since the default behavior is for the container to log all component method invocations except ACSComponentOperations#componentState().

Dealing with OffShoots: offshoots that follow the Corba Tie-approach enjoy automatic method invocation logging just like components do. In the rare event that you explicitly activate offshoots from your component, and want to suppress automatic logging for certain methods, return String(s) in the following format: OFFSHOOT::<offshootinterfacename>#<methodname>. Example for ALMA archive: "OFFSHOOT::Operational#retrieveFragment".

Note that returning Strings is fine (compared with more sophisticated Method objects) because the functional component interface methods cannot have parameter polymorphism thanks to IDL limitations. Thus there is no ambiguity in the method names.

Returns:
names of component methods for which the call-intercepting container should not log anything. Can be null.
Since:
ACS 5.0

Object alma::acs::container::ComponentHelper::_getInterfaceTranslator Object  defaultInterfaceTranslator  )  throws AcsJJavaComponentHelperEx [inline, protected]
 

To be overridden by subclass only if it wants its own interface translator to be used.

The returned interface translator must implement the component's operations interface, and must take care of translating in, inout parameters, forwarding the call to the respective method in the component implementation, and then translating out, inout parameters, and the return value.

It is foreseen that the necessary translations for most methods will be done automatically by the dynamic proxy classes. Some methods may require manual translation, e.g. if an expression that involves xml entity classes is too complex for the dynamic proxy.
On the other end of the spectrum, a manual implementation may choose to <emph>not</emph> unmarshal a marshalled binding object that it receives as an in parameter, because the binding object will only be routed through to another component, so first unmarshalling and later marshalling it would be an unnecessary performance loss. In that case, the manual interface translator could call an additional method in the component implementation which expects the marshalled xml rather than the binding object.

To facilitate the implementation of a manual interface translator, the defaultInterfaceTranslator is provided; it is a dynamic proxy object that implements the component's operations interface and forwards all calls to the component implementation created in _createComponentImpl, performing type translations in between. The methods that should be handled automatically can then be directly delegated to that proxy object, and only those methods that require special care need to be implemented by hand.

Parameters:
defaultInterfaceTranslator the default translator that the custon translator may use to delegate some or all method invocations to.
Returns:
the custom translator, or null if the default translator should be used.

abstract Class<? extends ACSComponentOperations> alma::acs::container::ComponentHelper::_getOperationsInterface  )  [protected, pure virtual]
 

Gets the xxOperations interface as generated by the IDL compiler.

This method must be provided by the component helper class.

Returns:
the Class object associated with the operations interface.

abstract Class<? extends Servant> alma::acs::container::ComponentHelper::_getPOATieClass  )  [protected, pure virtual]
 

This method must be provided by the component helper class. It must return the Class of the IDL-generated POA-Tie Servant, as in
return DummyComponentPOATie.class;.

final synchronized ComponentLifecycle alma::acs::container::ComponentHelper::getComponentImpl  )  throws AcsJComponentCreationEx, AcsJJavaComponentHelperEx [inline, protected]
 

Gets the component implementation. Must be the same object that also implements the functional interface obtained from getInternalInterface.

Returns:
The component implementation class that implements ComponentLifecycle and the functional interface.
Exceptions:
AcsJJavaComponentHelperEx if the component implementation construction failed or if the component does not implement its declared functional interface.

final Logger alma::acs::container::ComponentHelper::getComponentLogger  )  [inline, protected]
 

Gets the component logger.

Returns:
the logger to be used by subclasses if they have to log anything.

final String [] alma::acs::container::ComponentHelper::getComponentMethodsExcludedFromInvocationLogging  )  [inline, package]
 

See also:
_getComponentMethodsExcludedFromInvocationLogging

final Object alma::acs::container::ComponentHelper::getInterfaceTranslator  )  throws AcsJJavaComponentHelperEx [inline, package]
 

Method getInterfaceTranslator. Called by the container framework.

Returns:
Object
Exceptions:
AcsJJavaComponentHelperEx 

Class<?> alma::acs::container::ComponentHelper::getInternalInterface  )  throws AcsJJavaComponentHelperEx [inline, protected]
 

Gets the component's implemented functional IF. For instance, the method signatures can be the same as in the operations interface, except that the internal interface uses xml binding classes where the IDL-generated operations interface only contains stringified XML.

To be overridden by the component helper class only if the InternalInterface differs from the OperationsInterface.

Returns:
Class the Java Class of the internal interface.

final Class<? extends ACSComponentOperations> alma::acs::container::ComponentHelper::getOperationsInterface  )  throws AcsJJavaComponentHelperEx [inline, package]
 

Gets the xxOperations interface as generated by the IDL compiler by calling _getOperationsInterface().

Exceptions:
AcsJJavaComponentHelperEx if the subclass methdod throws something or returns null.

final Class<? extends Servant> alma::acs::container::ComponentHelper::getPOATieClass  )  throws AcsJJavaComponentHelperEx [inline, package]
 

Gets the Class object for the POA tie skeleton class. The POA tie class is generated by the IDL compiler and must have a constructor that takes the operations interface as its only parameter.

Returns:
the tie class.

boolean alma::acs::container::ComponentHelper::requiresOrbCentralLogSuppression  )  [inline, protected]
 

Do not overwrite this method unless you absolutely need to (currently only for the archive logger component!)

If true then the ORB logger will not send any log messages to the central (remote) Log service after activation of this component, regardless of any kind (env var, CDB, dynamic) log level settings. Local stdout logging by the ORB is not affected. Currently the ORB log suppression is not reversible: even when the component which requested this is unloaded, the ORB logger will not resume sending remote log messages. This may change in the future though.

Note that getComponentMethodsExcludedFromInvocationLogging can switch off automatic logging done by the container on behalf of the component. However, the ORB does not use a logger-per-component concept, and thus can't be told selectively to not log anything for a particualar component. The entire process (container and all components) are affected by suppressing the ORB's remote logging.

This method addresses the special problem of an infrastructural component that receives log messages from the Log service and writes them to the archive. Any message logged by the ORB on the receiver side would go back to the Log service and be received by the infrastructural component, with positive feedback leading to an explosion of log messages. Therefore we can't rely on log level settings and must categorically rule out such feedback loops.

Since:
ACS 7.0 when JacORB logs get sent to the Log service by default.
Returns:

final void alma::acs::container::ComponentHelper::setComponentInstanceName String  name  )  [inline, package]
 

Allows the container to set the component instance name. This name is used for the component logger and may also be useful in other ways.

Note that in a better design this name should be given in the constructor, but was added here as a separate method to avoid modifying existing component helper classes.

Parameters:
name the component instance name (CURL).
Since:
ACS 5.0


Member Data Documentation

String alma::acs::container::ComponentHelper::componentInstanceName [protected]
 

ComponentLifecycle alma::acs::container::ComponentHelper::m_componentImpl [private]
 

final Logger alma::acs::container::ComponentHelper::m_containerLogger [private]
 


The documentation for this class was generated from the following file:
Generated on Thu Apr 30 02:52:27 2009 for ACS Java API by doxygen 1.3.8