View Javadoc

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