1. /*
  2. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  3. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4. */
  5. package javax.jms;
  6. /** A <CODE>ServerSession</CODE> object is an application server object that
  7. * is used by a server to associate a thread with a JMS session (optional).
  8. *
  9. * <P>A <CODE>ServerSession</CODE> implements two methods:
  10. *
  11. * <UL>
  12. * <LI><CODE>getSession</CODE> - returns the <CODE>ServerSession</CODE>'s
  13. * JMS session.
  14. * <LI><CODE>start</CODE> - starts the execution of the
  15. * <CODE>ServerSession</CODE>
  16. * thread and results in the execution of the JMS session's
  17. * <CODE>run</CODE> method.
  18. * </UL>
  19. *
  20. * <P>A <CODE>ConnectionConsumer</CODE> implemented by a JMS provider uses a
  21. * <CODE>ServerSession</CODE> to process one or more messages that have
  22. * arrived. It does this by getting a <CODE>ServerSession</CODE> from the
  23. * <CODE>ConnectionConsumer</CODE>'s <CODE>ServerSessionPool</CODE> getting
  24. * the <CODE>ServerSession</CODE>'s JMS session; loading it with the messages;
  25. * and then starting the <CODE>ServerSession</CODE>.
  26. *
  27. * <P>In most cases the <CODE>ServerSession</CODE> will register some object
  28. * it provides as the <CODE>ServerSession</CODE>'s thread run object. The
  29. * <CODE>ServerSession</CODE>'s <CODE>start</CODE> method will call the
  30. * thread's <CODE>start</CODE> method, which will start the new thread, and
  31. * from it, call the <CODE>run</CODE> method of the
  32. * <CODE>ServerSession</CODE>'s run object. This object will do some
  33. * housekeeping and then call the <CODE>Session</CODE>'s <CODE>run</CODE>
  34. * method. When <CODE>run</CODE> returns, the <CODE>ServerSession</CODE>'s run
  35. * object can return the <CODE>ServerSession</CODE> to the
  36. * <CODE>ServerSessionPool</CODE>, and the cycle starts again.
  37. *
  38. * <P>Note that the JMS API does not architect how the
  39. * <CODE>ConnectionConsumer</CODE> loads the <CODE>Session</CODE> with
  40. * messages. Since both the <CODE>ConnectionConsumer</CODE> and
  41. * <CODE>Session</CODE> are implemented by the same JMS provider, they can
  42. * accomplish the load using a private mechanism.
  43. *
  44. * @version 1.0 - 9 March 1998
  45. * @author Mark Hapner
  46. * @author Rich Burridge
  47. *
  48. * @see javax.jms.ServerSessionPool
  49. * @see javax.jms.ConnectionConsumer
  50. */
  51. public interface ServerSession {
  52. /** Return the <CODE>ServerSession</CODE>'s <CODE>Session</CODE>. This must
  53. * be a <CODE>Session</CODE> created by the same <CODE>Connection</CODE>
  54. * that will be dispatching messages to it. The provider will assign one or
  55. * more messages to the <CODE>Session</CODE>
  56. * and then call <CODE>start</CODE> on the <CODE>ServerSession</CODE>.
  57. *
  58. * @return the server session's session
  59. *
  60. * @exception JMSException if the JMS provider fails to get the associated
  61. * session for this <CODE>ServerSession</CODE> due
  62. * to some internal error.
  63. **/
  64. Session
  65. getSession() throws JMSException;
  66. /** Cause the <CODE>Session</CODE>'s <CODE>run</CODE> method to be called
  67. * to process messages that were just assigned to it.
  68. *
  69. * @exception JMSException if the JMS provider fails to start the server
  70. * session to process messages due to some internal
  71. * error.
  72. */
  73. void
  74. start() throws JMSException;
  75. }