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 }