01: /*
02: * JBoss, Home of Professional Open Source.
03: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
04: * as indicated by the @author tags. See the copyright.txt file in the
05: * distribution for a full listing of individual contributors.
06: *
07: * This is free software; you can redistribute it and/or modify it
08: * under the terms of the GNU Lesser General Public License as
09: * published by the Free Software Foundation; either version 2.1 of
10: * the License, or (at your option) any later version.
11: *
12: * This software is distributed in the hope that it will be useful,
13: * but WITHOUT ANY WARRANTY; without even the implied warranty of
14: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15: * Lesser General Public License for more details.
16: *
17: * You should have received a copy of the GNU Lesser General Public
18: * License along with this software; if not, write to the Free
19: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21: */
22: package javax.ejb;
23:
24: /**
25: * <P>The EntityContext interface provides an instance with access to
26: * the container-provided runtime context of an entity enterprise Bean
27: * instance. The container passes the EntityContext interface to an entity
28: * enterprise Bean instance after the instance has been created.</P>
29: *
30: * <P>The EntityContext interface remains associated with the instance for the
31: * lifetime of the instance. Note that the information that the instance
32: * obtains using the EntityContext interface (such as the result of the
33: * getPrimaryKey() method) may change, as the container assigns the instance
34: * to different EJB objects during the instance's life cycle.</P>
35: */
36: public interface EntityContext extends EJBContext {
37:
38: /**
39: * <P>Obtain a reference to the EJB local object that is currently associated with the instance.</P>
40: *
41: * <P>An instance of an entity enterprise Bean can call this method only when the instance is associated
42: * with an EJB local object identity, i.e. in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove, ejbLoad,
43: * ejbStore, and business methods.</P>
44: *
45: * <P>An instance can use this method, for example, when it wants to pass a reference to itself in a
46: * method argument or result.</P>
47: *
48: * @return The EJB local object currently associated with the instance.
49: * @exception java.lang.IllegalStateException - if the instance invokes this method while the instance
50: * is in a state that does not allow the instance to invoke this method, or if the instance does not have
51: * a local interface.
52: */
53: public EJBLocalObject getEJBLocalObject()
54: throws IllegalStateException;
55:
56: /**
57: * <P>Obtain a reference to the EJB object that is currently associated with the instance.</P>
58: *
59: * <P>An instance of an entity enterprise Bean can call this method only when the instance is associated
60: * with an EJB object identity, i.e. in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove, ejbLoad,
61: * ejbStore, and business methods.</P>
62: *
63: * <P>An instance can use this method, for example, when it wants to pass a reference to itself in a method
64: * argument or result.</P>
65: *
66: * @return The EJB object currently associated with the instance.
67: * @exception java.lang.IllegalStateException - Thrown if the instance invokes this method while the instance
68: * is in a state that does not allow the instance to invoke this method, or if the instance does not have a
69: * remote interface.
70: */
71: public EJBObject getEJBObject() throws IllegalStateException;
72:
73: /**
74: * <P>Obtain the primary key of the EJB object that is currently associated with this instance.</P>
75: *
76: * <P>An instance of an entity enterprise Bean can call this method only when the instance is associated
77: * with an EJB object identity, i.e. in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove, ejbLoad,
78: * ejbStore, and business methods.</P>
79: *
80: * <P><B>Note:</B> The result of this method is that same as the result of getEJBObject().getPrimaryKey().</P>
81: *
82: * @return The primary key currently associated with the instance.
83: * @exception java.lang.IllegalStateException - Thrown if the instance invokes this method while the
84: * instance is in a state that does not allow the instance to invoke this method.
85: */
86: public Object getPrimaryKey() throws IllegalStateException;
87: }
|