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