1   /*
    2   * JBoss, Home of Professional Open Source
    3   * Copyright 2005, JBoss Inc., and individual contributors as indicated
    4   * by the @authors tag. See the copyright.txt in the distribution for a
    5   * full listing of individual contributors.
    6   *
    7   * This is free software; you can redistribute it and/or modify it
    8   * under the terms of the GNU Lesser General Public License as
    9   * 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() throws IllegalStateException;
   54   
   55     /**
   56      * <P>Obtain a reference to the EJB object that is currently associated with the instance.</P>
   57      *
   58      * <P>An instance of an entity enterprise Bean can call this method only when the instance is associated
   59      * with an EJB object identity, i.e. in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove, ejbLoad,
   60      * ejbStore, and business methods.</P>
   61      *
   62      * <P>An instance can use this method, for example, when it wants to pass a reference to itself in a method
   63      * argument or result.</P>
   64      *
   65      * @return The EJB object currently associated with the instance.
   66      * @exception java.lang.IllegalStateException - Thrown if the instance invokes this method while the instance
   67      * is in a state that does not allow the instance to invoke this method, or if the instance does not have a
   68      * remote interface.
   69      */
   70     public EJBObject getEJBObject() throws IllegalStateException;
   71   
   72     /**
   73      * <P>Obtain the primary key of the EJB object that is currently associated with this instance.</P>
   74      *
   75      * <P>An instance of an entity enterprise Bean can call this method only when the instance is associated
   76      * with an EJB object identity, i.e. in the ejbActivate, ejbPassivate, ejbPostCreate, ejbRemove, ejbLoad,
   77      * ejbStore, and business methods.</P>
   78      *
   79      * <P><B>Note:</B> The result of this method is that same as the result of getEJBObject().getPrimaryKey().</P>
   80      *
   81      * @return The primary key currently associated with the instance.
   82      * @exception java.lang.IllegalStateException - Thrown if the instance invokes this method while the
   83      * instance is in a state that does not allow the instance to invoke this method.
   84      */
   85     public Object getPrimaryKey() throws IllegalStateException;
   86   }