1. /*
  2. * @(#)file CommunicatorServerMBean.java
  3. * @(#)author Sun Microsystems, Inc.
  4. * @(#)version 1.25
  5. * @(#)lastedit 03/12/19
  6. *
  7. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  8. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  9. *
  10. */
  11. package com.sun.jmx.snmp.daemon;
  12. /**
  13. * Defines generic behaviour for the server
  14. * part of a connector or an adaptor. Most connectors or adaptors extend <CODE>CommunicatorServer</CODE>
  15. * and inherit this behaviour. Connectors or adaptors that do not fit into this model do not extend
  16. * <CODE>CommunicatorServer</CODE>.
  17. * <p>
  18. * An <CODE>CommunicatorServer</CODE> is an active object, it listens for client requests
  19. * and processes them in its own thread. When necessary, a <CODE>CommunicatorServer</CODE>
  20. * creates other threads to process multiple requests concurrently.
  21. * <p>
  22. * A <CODE>CommunicatorServer</CODE> object can be stopped by calling the <CODE>stop</CODE>
  23. * method. When it is stopped, the <CODE>CommunicatorServer</CODE> no longer listens to client
  24. * requests and no longer holds any thread or communication resources.
  25. * It can be started again by calling the <CODE>start</CODE> method.
  26. * <p>
  27. * A <CODE>CommunicatorServer</CODE> has a <CODE>state</CODE> property which reflects its
  28. * activity.
  29. * <p>
  30. * <TABLE>
  31. * <TR><TH>CommunicatorServer</TH> <TH>State</TH></TR>
  32. * <TR><TD><CODE>stopped</CODE></TD> <TD><CODE>OFFLINE</CODE></TD></TR>
  33. * <TR><TD><CODE>starting</CODE></TD> <TD><CODE>STARTING</CODE></TD></TR>
  34. * <TR><TD><CODE>running</CODE></TD> <TD><CODE>ONLINE</CODE></TD></TR>
  35. * <TR><TD><CODE>stopping</CODE></TD> <TD><CODE>STOPPING</CODE></TD></TR>
  36. * </TABLE>
  37. * <p>
  38. * The <CODE>STARTING</CODE> state marks the transition from <CODE>OFFLINE</CODE> to
  39. * <CODE>ONLINE</CODE>.
  40. * <p>
  41. * The <CODE>STOPPING</CODE> state marks the transition from <CODE>ONLINE</CODE> to
  42. * <CODE>OFFLINE</CODE>. This occurs when the <CODE>CommunicatorServer</CODE> is
  43. * finishing or interrupting active requests.
  44. * <p>
  45. * A <CODE>CommunicatorServer</CODE> may serve several clients concurrently. The
  46. * number of concurrent clients can be limited using the property
  47. * <CODE>maxActiveClientCount</CODE>. The default value of this property is
  48. * defined by the subclasses.
  49. * <p>
  50. * When a <CODE>CommunicatorServer</CODE> is unregistered from the MBeanServer,
  51. * it is stopped automatically.
  52. *
  53. * <p><b>This API is a Sun Microsystems internal API and is subject
  54. * to change without notice.</b></p>
  55. * @version 1.25 12/19/03
  56. * @author Sun Microsystems, Inc
  57. */
  58. public interface CommunicatorServerMBean {
  59. /**
  60. * Starts this <CODE>CommunicatorServer</CODE>.
  61. * <p>
  62. * Has no effect if this <CODE>CommunicatorServer</CODE> is <CODE>ONLINE</CODE> or
  63. * <CODE>STOPPING</CODE>.
  64. */
  65. public void start() ;
  66. /**
  67. * Stops this <CODE>CommunicatorServer</CODE>.
  68. * <p>
  69. * Has no effect if this <CODE>CommunicatorServer</CODE> is <CODE>OFFLINE</CODE> or
  70. * <CODE>STOPPING</CODE>.
  71. */
  72. public void stop() ;
  73. /**
  74. * Tests if the <CODE>CommunicatorServer</CODE> is active.
  75. *
  76. * @return True if connector is <CODE>ONLINE</CODE> false otherwise.
  77. */
  78. public boolean isActive() ;
  79. /**
  80. * Waits untill either the State attribute of this MBean equals the specified <VAR>state</VAR> parameter,
  81. * or the specified <VAR>timeOut</VAR> has elapsed. The method <CODE>waitState</CODE> returns with a boolean value indicating whether
  82. * the specified <VAR>state</VAR> parameter equals the value of this MBean's State attribute at the time the method terminates.
  83. *
  84. * Two special cases for the <VAR>timeOut</VAR> parameter value are:
  85. * <UL><LI> if <VAR>timeOut</VAR> is negative then <CODE>waitState</CODE> returns immediately (i.e. does not wait at all),</LI>
  86. * <LI> if <VAR>timeOut</VAR> equals zero then <CODE>waitState</CODE> waits untill the value of this MBean's State attribute
  87. * is the same as the <VAR>state</VAR> parameter (i.e. will wait indefinitely if this condition is never met).</LI></UL>
  88. *
  89. * @param state The value of this MBean's State attribute
  90. * to wait for. <VAR>state</VAR> can be one of:
  91. * <ul>
  92. * <li><CODE>CommunicatorServer.OFFLINE</CODE>,</li>
  93. * <li><CODE>CommunicatorServer.ONLINE</CODE>,</li>
  94. * <li><CODE>CommunicatorServer.STARTING</CODE>,</li>
  95. * <li><CODE>CommunicatorServer.STOPPING</CODE>.</li>
  96. * </ul>
  97. * @param timeOut The maximum time to wait for, in
  98. * milliseconds, if positive.
  99. * Infinite time out if 0, or no waiting at all if negative.
  100. *
  101. * @return true if the value of this MBean's State attribute is the
  102. * same as the <VAR>state</VAR> parameter; false otherwise.
  103. */
  104. public boolean waitState(int state , long timeOut) ;
  105. /**
  106. * Gets the state of this <CODE>CommunicatorServer</CODE> as an integer.
  107. *
  108. * @return <CODE>ONLINE</CODE>, <CODE>OFFLINE</CODE>, <CODE>STARTING</CODE> or <CODE>STOPPING</CODE>.
  109. */
  110. public int getState() ;
  111. /**
  112. * Gets the state of this <CODE>CommunicatorServer</CODE> as a string.
  113. *
  114. * @return One of the strings "ONLINE", "OFFLINE", "STARTING" or "STOPPING".
  115. */
  116. public String getStateString() ;
  117. /**
  118. * Gets the host name used by this <CODE>CommunicatorServer</CODE>.
  119. *
  120. * @return The host name used by this <CODE>CommunicatorServer</CODE>.
  121. */
  122. public String getHost() ;
  123. /**
  124. * Gets the port number used by this <CODE>CommunicatorServer</CODE>.
  125. *
  126. * @return The port number used by this <CODE>CommunicatorServer</CODE>.
  127. */
  128. public int getPort() ;
  129. /**
  130. * Sets the port number used by this <CODE>CommunicatorServer</CODE>.
  131. *
  132. * @param port The port number used by this <CODE>CommunicatorServer</CODE>.
  133. *
  134. * @exception java.lang.IllegalStateException This method has been invoked
  135. * while the communicator was ONLINE or STARTING.
  136. */
  137. public void setPort(int port) throws java.lang.IllegalStateException ;
  138. /**
  139. * Gets the protocol being used by this <CODE>CommunicatorServer</CODE>.
  140. * @return The protocol as a string.
  141. */
  142. public abstract String getProtocol() ;
  143. }