01: /**********************************************************************
02: Copyright (c) 2003 Mike Martin and others. All rights reserved.
03: Licensed under the Apache License, Version 2.0 (the "License");
04: you may not use this file except in compliance with the License.
05: You may obtain a copy of the License at
06:
07: http://www.apache.org/licenses/LICENSE-2.0
08:
09: Unless required by applicable law or agreed to in writing, software
10: distributed under the License is distributed on an "AS IS" BASIS,
11: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12: See the License for the specific language governing permissions and
13: limitations under the License.
14:
15:
16: Contributors:
17: 2003 Andy Jefferson - commented
18: ...
19: **********************************************************************/package org.jpox.sco;
20:
21: import org.jpox.state.FetchPlanState;
22:
23: /**
24: * Representation of a wrapper/proxy for a mutable SCO type supported by JPOX.
25: * An implementation of this interface must have a constructor with the arguments
26: * <i>{@link org.jpox.StateManager} ownerSM</i>, <i>String fieldName</i>.
27: * The constructor must be capable of taking nulls for these arguments to create a non-managed wrapper
28: * which effectively just acts like an unwrapped object.
29: *
30: * @version $Revision: 1.24 $
31: */
32: public interface SCO {
33: /**
34: * Method to initialise the SCO for use using an existing object of the same or compatible type.
35: * @param value the object from which to copy the value.
36: * @param forInsert Whether the object needs inserting in the datastore with this value
37: * @param forUpdate Whether the object needs updating in the datastore with this value
38: * @throws ClassCastException Thrown if the given object is not of a type that's compatible with this
39: * second-class wrapper object.
40: */
41: void initialise(Object value, boolean forInsert, boolean forUpdate)
42: throws ClassCastException;
43:
44: /**
45: * Method to initialise the SCO for use.
46: * This can be utilised to perform any eager loading of information from the datastore.
47: */
48: void initialise();
49:
50: /**
51: * Accessor for the field name.
52: * @return field name, or null if no longer associated with an object
53: */
54: String getFieldName();
55:
56: /**
57: * Accessor for the owner object of the SCO instance.
58: * Usually it's an instance of {@link javax.jdo.spi.PersistenceCapable}.
59: * @return owner object, or null if no longer associated with an object
60: */
61: Object getOwner();
62:
63: /**
64: * Nullifies references to the owner Object and field. Thereafter the SCO is no longer associated with the
65: * owner and thus should not issue any request to the datastore.
66: */
67: void unsetOwner();
68:
69: /**
70: * Method to return the value of the unwrapped type.
71: * @return The value that is wrapped by this object.
72: */
73: Object getValue();
74:
75: /**
76: * Mutable second class objects are required to provide a public clone() method so that copying
77: * of persistable objects can take place. This mustn't throw a {@link CloneNotSupportedException}.
78: * @return A clone of the object
79: */
80: Object clone();
81:
82: /**
83: * Method to return a detached copy of this object.
84: * Detaches all components of this object that are also PersistenceCapable.
85: * @param state State of the detachment process
86: * @return The detached copy
87: */
88: Object detachCopy(FetchPlanState state);
89:
90: /**
91: * Method to return an attached copy of this object.
92: * Attaches all components of this object that are also {@link javax.jdo.spi.PersistenceCapable}.
93: * @param value The object value from the detached instance
94: */
95: void attachCopy(Object value);
96: }
|