/* * ALMA - Atacama Large Millimiter Array * (c) European Southern Observatory, 2002 * Copyright by ESO (in the framework of the ALMA collaboration), * All rights reserved * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * MA 02111-1307 USA */ package alma.acs.container; import java.util.concurrent.ThreadFactory; import org.omg.PortableServer.Servant; import alma.ACS.OffShoot; import alma.ACS.OffShootOperations; import alma.JavaContainerError.wrappers.AcsJContainerServicesEx; import alma.acs.logging.AcsLogger; import alma.acs.nc.AcsEventPublisher; import alma.acs.nc.AcsEventSubscriber; import com.cosylab.CDB.DAL; /** * Through this interface, the container offers services to its hosted components. * The component must call these methods explicitly; in this respect, * ContainerServices is different from the other services that the container * provides without the component implementation knowing about it. * It can be thought of as a callback handle or a library. *

* Currently, methods are added to this interface as the functionality becomes available. * At some point we will have to declutter the interface by introducing 2nd-level interfaces * that harbor cohesive functionality. For example, instead of calling * myContainerServices.getComponent(...), the new call will then be something like * myContainerServices.communication().getComponent(...). *

* created on Oct 24, 2002 12:56:36 PM * @author hsommer */ public interface ContainerServicesBase { ///////////////////////////////////////////////////////////// // basic needs ///////////////////////////////////////////////////////////// /** * Delivers the unique instance name for the component. * The name must have been specified at deployment time in the CDB * (for static components like the famous "LAMP1" example), * or must have been given to the manager at runtime by the client who creates * a dynamic component (or was invented by the manager if none was given). * @return the unique component instance name */ public String getName(); /** * Gets a Logger object that the component should use for logging. *

* The Logger will be set up with a namespace specific to the component * that uses this ContainerServices instance. *

* Specific logger extensions that only apply to certain subsystems can be used * by wrapping this logger with a class such as {@link alma.acs.logging.domainspecific.AntennaContextLogger}. * * @return Logger */ public AcsLogger getLogger(); /** * Convenience method for accessing the Configuration Database. *

* Currently more than a convenience, given that the CDB is not yet a Java component, * but a separate service... * * @return the CDB interface * @throws ContainerException */ public DAL getCDB() throws AcsJContainerServicesEx; ///////////////////////////////////////////////////////////// // advanced stuff, only for special cases ///////////////////////////////////////////////////////////// /** * Activates a CORBA servant that implements alma.ACS.OffShoot. * The purpose of the OffShoot marker interface is to crack down on uncontrolled * activation of just any CORBA services by Java components, * while allowing this for selected subtypes of OffShoot, like * {@link alma.ACS.Callback}. *

* The OffShoot servant can be either a subclass of the xyzPOA skeleton, or a xyzPOATie instance * (delegation model). * Since ACS 4.1.2, a tie servant is detected, and interception code gets inserted between the * POATie skeleton and the offshoot implementation class. This way, the container * can intercept (and log) calls to offshoots in the same way as it does for calls to components. * It is therefore recommended to use the tie approach for all offshoot servants, * unless there is a reason to avoid container interception. *

* Note that since ACS 9.0 we are using generics to express that the offshoot impl object must * be both a corba servant and implement OffShootOperations. * * @param cbServant the CORBA-generated servant, e.g. CBdoublePOA; * must implement alma.ACS.OffShootOperations. * @return The corba-activated offshoot object, which needs a narrow-cast to the subtype, like * CBdouble myCBdouble = alma.ACS.CBdoubleHelper.narrow(...). * @throws ContainerException if anything goes wrong, * especially if cbServant is not an OffShoot. */ public OffShoot activateOffShoot(T cbServant) throws AcsJContainerServicesEx; /** * Deactivates the offshoot object previously activated through the {@link #activateOffShoot(Object, Class)} method. * Caution: this method returns immediately, while the underlying * {@link org.omg.PortableServer.POAOperations#deactivate_object(byte[])} still * works on the deactivation. If {@link #activateOffShoot(Servant)} is called too shortly * after deactivation, an exception will be thrown. TODO: find a remedy * * @param offshootImpl the offshoot object implementation * @throws AcsJContainerServicesEx if something goes wrong, e.g., if the corresponding offshoot servant was not active. */ public void deactivateOffShoot(Object offshootImpl) throws AcsJContainerServicesEx; /** * More specialized methods are available from the AdvancedContainerServices. */ public AdvancedContainerServices getAdvancedContainerServices(); ///////////////////////////////////////////////////////////// // other ///////////////////////////////////////////////////////////// /** * Gets a ThreadFactory, to be used as input for other classes from the concurrent library * (such as ThreadPoolExecutor), or simply to create new Threads. *

* All user-created threads should come from the factory returned here, so "new Thread(...)" should * not appear anywhere in component code. *

* The returned thread factory creates new threads configured to run well in the container environment, e.g. *

* @return the thread factory to be used by the component to create new threads. */ public ThreadFactory getThreadFactory(); ///////////////////////////////////////////////////////////// // Notification Channel API ///////////////////////////////////////////////////////////// /** * Creates a new {@link AcsEventPublisher} object for a given channel. * It is the abstraction of a Corba Notification Channel supplier, a DDS publisher, * or a publisher for some other supported pub/sub technology. *

* The user is expected to call {@link alma.acs.nc.AcsEventPublisher#disconnect()} when the publisher is no longer needed. * To avoid resource problems, the ContainerServices object calls this method during its own deactivation, * just in case the user forgot to do so. * * @param channelName The Notification Channel name where events will be published. * @param eventType The type of event that can be sent using the AcsEventPublisher, e.g. "MySchedulingEvent.class". * Specifying the type offers additional compile time checking. * It should generally be used unless more than one event type must be sent through this publisher, * in which case you can specify a common base type (e.g. "IDLEntity" in case of different IDL-generated structs), * or just "Object" for total type freedom (though the underlying pub-sub framework may later throw runtime exceptions * if unsupported event types get used). * @return a Notification Channel publisher, that will get automatically stopped and disconnected when the component is unloaded, * or the client disconnected, depending on the case, if the user doesn't do so. * @throws AcsJContainerServicesEx if anything goes wrong while creating the publisher */ public AcsEventPublisher createNotificationChannelPublisher(String channelName, Class eventType) throws AcsJContainerServicesEx; /** * Similar to {@link #createNotificationChannelPublisher(String, Class)}, * but with additional NC domain specification. *

* Details of this NC domain concept: *

* * @param ncDomain The Notification Channel Service Domain name. * @param eventType * @see #createNotificationChannelSubscriber(String, String) */ public AcsEventPublisher createNotificationChannelPublisher(String channelName, String ncDomain, Class eventType) throws AcsJContainerServicesEx; /** * Creates a new {@link AcsEventSubscriber} object, which is the abstraction of a Notification Channel subscriber (consumer), * for the given channel name. * The created subscriber will be automatically disconnected when the component or client that created it through this method * is finished, in case the user doesn't explicitly do it before. * * @param channelName The Notification Channel name to listen to * @param eventType The type of event that can be sent using the AcsEventSubscriber, e.g. "MySchedulingEvent.class". * The specific event type should be used unless more than one event types must be received by this subscriber, * in which case you can specify a common base type (e.g. "IDLEntity.class" in case of different IDL-generated structs), * or just "Object" for total type freedom (though the underlying pub-sub framework may later throw runtime exceptions * if unsupported event types are received). * @return a Notification Channel subscriber, to which the user can attach one or more handlers for each data type, and that will * be automatically disconnected if the user doesn't do so. * @throws AcsJContainerServicesEx if anything goes wrong while creating the subscriber */ public AcsEventSubscriber createNotificationChannelSubscriber(String channelName, Class eventType) throws AcsJContainerServicesEx; /** * Creates a new {@link AcsEventSubscriber} object, which is the abstraction of a Notification Channel subscriber (consumer), * for the given channel name and notify service domain name. * The created subscriber will be automatically disconnected when the component or client that created it through this method * is finished, in case the user doesn't explicitly do it before. *

* Details of the NC domain concept: *

    *
  • All publishers and subscribers that access an NC must consistently use the same NC domain name. *
  • The CDB may specify a mapping of NC domain to a notify service, which then decides where the NC is hosted. *
  • Specifying the NC domain through the API as opposed to doing it in the NC's CDB description * allows mapping of "dynamic" NCs to notify services, whose names are not known at deployment time. * This may be the case for NCs created by 3rd party software such as the alarm system. *
* * @param channelName The Notification Channel name to listen to * @param ncDomain The Notification Channel Service Domain name. * @param eventType See {@link #createNotificationChannelPublisher(String, Class)}. * @return a Notification Channel subscriber, to which the user can attach one or more handlers for each data type, and that will * be automatically disconnected if the user doesn't do so. * @throws AcsJContainerServicesEx if anything goes wrong while creating the subscriber */ public AcsEventSubscriber createNotificationChannelSubscriber(String channelName, String ncDomain, Class eventType) throws AcsJContainerServicesEx; }