00001 /* 00002 * Controllable.hpp 00003 * 00004 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_CONTROLLABLE_HPP 00017 #define COH_CONTROLLABLE_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/run/xml/XmlElement.hpp" 00022 00023 COH_OPEN_NAMESPACE2(coherence,util) 00024 00025 using coherence::run::xml::XmlElement; 00026 00027 00028 /** 00029 * The Controllable interface represents a configurable dameon-like object, 00030 * quite oftenly referred to as a <i>service</i>, that usually operates on its 00031 * own thread and has a controllable life cycle. 00032 * 00033 * @author jh 2007.12.12 00034 */ 00035 class COH_EXPORT Controllable 00036 : public interface_spec<Controllable> 00037 { 00038 // ----- Controllable interface ----------------------------------------- 00039 00040 public: 00041 /** 00042 * Configure the controllable service. 00043 * 00044 * This method can only be called before the controllable 00045 * service is started. 00046 * 00047 * @param vXml an XmlElement carrying configuration information 00048 * specific to the Controllable object 00049 * 00050 * virtual void IllegalStateException thrown if the service is 00051 * already running 00052 * virtual void IllegalArgumentException thrown if the configuration 00053 * information is invalid 00054 */ 00055 virtual void configure(XmlElement::View vXml) = 0; 00056 00057 /** 00058 * Determine whether or not the controllable service is running. 00059 * This method returns false before a service is started, while 00060 * the service is starting, while a service is shutting down and 00061 * after the service has stopped. It only returns true after 00062 * completing its start processing and before beginning its 00063 * shutdown processing. 00064 * 00065 * @return true if the service is running; false otherwise 00066 */ 00067 virtual bool isRunning() const = 0; 00068 00069 /** 00070 * Start the controllable service. 00071 * 00072 * This method should only be called once per the life cycle 00073 * of the Controllable service. This method has no affect if the 00074 * service is already running. 00075 * 00076 * virtual void IllegalStateException thrown if a service does not 00077 * support being re-started, and the service was 00078 * already started and subsequently stopped and then 00079 * an attempt is made to start the service again; also 00080 * thrown if the Controllable service has not been 00081 * configured 00082 */ 00083 virtual void start() = 0; 00084 00085 /** 00086 * Stop the controllable service. This is a controlled shut-down, 00087 * and is preferred to the {@link #stop()} method. 00088 * 00089 * This method should only be called once per the life cycle of the 00090 * controllable service. Calling this method for a service that has 00091 * already stopped has no effect. 00092 */ 00093 virtual void shutdown() = 0; 00094 00095 /** 00096 * Hard-stop the controllable service. Use {@link #shutdown()} 00097 * for normal service termination. Calling this method for a service 00098 * that has already stopped has no effect. 00099 */ 00100 virtual void stop() = 0; 00101 }; 00102 00103 COH_CLOSE_NAMESPACE2 00104 00105 #endif // COH_CONTROLLABLE_HPP