View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18  /*
    19   * InstanceLifecycleEvent.java
    20   *
    21   */
    22
    23  package javax.jdo.listener;
    24
    25  import javax.jdo.spi.I18NHelper;
    26
    27  /**
    28   * This is the event class used in life cycle event notifications.
    29   * <P>Note that although InstanceLifecycleEvent inherits Serializable interface
    30   * from EventObject, it is not intended to be Serializable. Appropriate
    31   * serialization methods are implemented to throw NotSerializableException.
    32   * @version 2.0
    33   * @since 2.0
    34   */
    35  public class InstanceLifecycleEvent
    36      extends java.util.EventObject {
    37
    38      private static final int FIRST_EVENT_TYPE = 0;
    39      public static final int CREATE = 0;
    40      public static final int LOAD = 1;
    41      public static final int STORE = 2;
    42      public static final int CLEAR = 3;
    43      public static final int DELETE = 4;
    44      public static final int DIRTY = 5;
    45      public static final int DETACH = 6;
    46      public static final int ATTACH = 7;
    47      private static final int LAST_EVENT_TYPE = 7;
    48
    49      /** The Internationalization message helper.
    50       */
    51      private final static I18NHelper msg = I18NHelper.getInstance ("javax.jdo.Bundle"); //NOI18N
    52
    53      /**
    54       * The event type that triggered the construction of this event object.
    55       */
    56      private final int eventType;
    57
    58      /**
    59       * The "other" object associated with the event.
    60       */
    61      private final Object target;
    62
    63      /**
    64       *	Creates a new event object with the specified
    65       *	<code>source</code> and <code>type</code>.
    66       * @param source the instance that triggered the event
    67       * @param type the event type
    68       * @since 2.0
    69       */
    70      public InstanceLifecycleEvent (Object source, int type) {
    71          this(source, type, null);
    72      }
    73
    74      /**
    75       *	Creates a new event object with the specified
    76       *	<code>source</code>, <code>type</code>, and <code>target</code>.
    77       * @param source the instance that triggered the event
    78       * @param type the event type
    79       * @param target the "other" instance
    80       * @since 2.0
    81       */
    82      public InstanceLifecycleEvent (Object source, int type, Object target) {
    83          super (source);
    84          if (type < FIRST_EVENT_TYPE || type > LAST_EVENT_TYPE) {
    85              throw new IllegalArgumentException(msg.msg("EXC_IllegalEventType"));
    86          }
    87          eventType = type;
    88          this.target = target;
    89      }
    90
    91      /**
    92       *	Returns the event type that triggered this event.
    93       * @return the event type
    94       * @since 2.0
    95       */
    96      public int getEventType () {
    97          return eventType;
    98      }
    99
    100     /**
    101      * The source object of the Event.  Although not deprecated,
    102      * it is recommended that the the methods
    103      * <code>getPersistentInstance()</code> and
    104      * <code>getDetachedInstance()</code> be used instead.
    105      *
    106      * @return   The persistent instance on any pre- callback except preAttach,
    107      * or the detached instance for a postDetach or preAttach callback.
    108      *
    109      * @see #getPersistentInstance()
    110      * @see #getDetachedInstance()
    111      * @see "Section 12.15, Java Data Objects 2.0 Specification"
    112      */
    113     public Object getSource() {
    114         return super.getSource();
    115     }
    116
    117     /**
    118      * The target object of the Event.  Although not deprecated,
    119      * it is recommended that the the methods
    120      * <code>getPersistentInstance()</code> and
    121      * <code>getDetachedInstance()</code> be used instead.
    122      *
    123      * @return The detached instance for preDetach and postAttach,
    124      * the persistent instance otherwise.
    125      *
    126      * @since 2.0
    127      * @see #getPersistentInstance()
    128      * @see #getDetachedInstance()
    129      * @see "Section 12.15, Java Data Objects 2.0 Specification"
    130      */
    131     public Object getTarget () {
    132         return target;
    133     }
    134
    135     /**
    136      * Returns the persistent instance involved in the event.
    137      *
    138      * @return The persistent instance involved in the event, or null if there
    139      * was none.
    140      *
    141      * @see "Section 12.15, Java Data Objects 2.0 Specification"
    142      */
    143     public Object getPersistentInstance() {
    144         switch (getEventType()) {
    145             case DETACH:
    146                 return target == null
    147                         ? getSource()   // preDetach:  source is persistent instance
    148                         : getTarget();  // postDetach:  target is persistent instance
    149             case ATTACH:
    150                 return target == null
    151                         ? null          // preAttach:  no persistent instance yet
    152                         : getSource();  // postAttach:  source is persistent instance
    153         }
    154
    155         // for all other events, source is persistent instance
    156         return getSource();
    157     }
    158
    159     /**
    160      * Returns the detached instance involved in the event.
    161      *
    162      * @return The detached instance involved in the event, or null if there was none.
    163      *
    164      * @see "Section 12.15, Java Data Objects 2.0 Specification"
    165      */
    166     public Object getDetachedInstance() {
    167         switch (getEventType()) {
    168             case DETACH:
    169                 return target == null
    170                         ? null          // preDetach:  no detached instance yet
    171                         : getSource();  // postDetach:  source is detached instance
    172             case ATTACH:
    173                 return target == null
    174                         ? getSource()   // preAttach:  source is detached instance
    175                         : getTarget();  // postAttach:  target is detached instance
    176         }
    177
    178         // for all other events, there is no detached instance
    179         return null;
    180     }
    181
    182     /**
    183      * Serialization is not supported for InstanceLifecycleEvents.
    184      * param out the output stream
    185      * @since 2.0
    186      */
    187     private void writeObject(java.io.ObjectOutputStream out)
    188         throws java.io.IOException {
    189         throw new java.io.NotSerializableException();
    190     }
    191 }