1. /*
  2. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  3. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4. */
  5. package javax.ejb;
  6. import java.util.*;
  7. import java.security.Identity;
  8. /**
  9. * The EntityContext interface provides an instance with access to the
  10. * container-provided runtime context of an entity enterprise Bean instance.
  11. * The container passes the EntityContext interface to an entity enterprise
  12. * Bean instance after the instance has been created.
  13. *
  14. * <p> The EntityContext interface remains associated with the instance for
  15. * the lifetime of the instance. Note that the information that the instance
  16. * obtains using the EntityContext interface (such as the result of the
  17. * getPrimaryKey() method) may change, as the container assigns the instance
  18. * to different EJB objects during the instance's life cycle.
  19. */
  20. public interface EntityContext extends EJBContext
  21. {
  22. /**
  23. * Obtain a reference to the EJB local object that is currently
  24. * associated with the instance.
  25. *
  26. * <p> An instance of an entity enterprise Bean can call this method only
  27. * when the instance is associated with an EJB local object identity, i.e.
  28. * in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove,
  29. * ejbLoad, ejbStore, and business methods.
  30. *
  31. * <p> An instance can use this method, for example, when it wants to
  32. * pass a reference to itself in a method argument or result.
  33. *
  34. * @return The EJB local object currently associated with the instance.
  35. *
  36. * @exception IllegalStateException if the instance invokes this
  37. * method while the instance is in a state that does not allow the
  38. * instance to invoke this method, or if the instance does not have
  39. * a local interface.
  40. */
  41. EJBLocalObject getEJBLocalObject() throws IllegalStateException;
  42. /**
  43. * Obtain a reference to the EJB object that is currently associated with
  44. * the instance.
  45. *
  46. * <p> An instance of an entity enterprise Bean can call this method only
  47. * when the instance is associated with an EJB object identity, i.e.
  48. * in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove,
  49. * ejbLoad, ejbStore, and business methods.
  50. *
  51. * <p> An instance can use this method, for example, when it wants to
  52. * pass a reference to itself in a method argument or result.
  53. *
  54. * @return The EJB object currently associated with the instance.
  55. *
  56. * @exception IllegalStateException Thrown if the instance invokes this
  57. * method while the instance is in a state that does not allow the
  58. * instance to invoke this method, or if the instance does not have
  59. * a remote interface.
  60. */
  61. EJBObject getEJBObject() throws IllegalStateException;
  62. /**
  63. * Obtain the primary key of the EJB object that is currently
  64. * associated with this instance.
  65. *
  66. * <p> An instance of an entity enterprise Bean can call this method only
  67. * when the instance is associated with an EJB object identity, i.e.
  68. * in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove,
  69. * ejbLoad, ejbStore, and business methods.
  70. *
  71. * <p><b>Note</b>: The result of this method is that same as the
  72. * result of getEJBObject().getPrimaryKey().
  73. *
  74. * @return The primary key currently associated with the instance.
  75. *
  76. * @exception IllegalStateException Thrown if the instance invokes this
  77. * method while the instance is in a state that does not allow the
  78. * instance to invoke this method.
  79. */
  80. Object getPrimaryKey() throws IllegalStateException;
  81. }