001: /*
002: *
003: * JMoney - A Personal Finance Manager
004: * Copyright (c) 2004 Nigel Westbury <westbury@users.sourceforge.net>
005: *
006: *
007: * This program is free software; you can redistribute it and/or modify
008: * it under the terms of the GNU General Public License as published by
009: * the Free Software Foundation; either version 2 of the License, or
010: * (at your option) any later version.
011: *
012: * This program is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
015: * GNU General Public License for more details.
016: *
017: * You should have received a copy of the GNU General Public License
018: * along with this program; if not, write to the Free Software
019: * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
020: *
021: */
022:
023: package net.sf.jmoney.model2;
024:
025: /**
026: * Interface into a key object that holds the data required to
027: * obtain an extendable data object.
028: * <P>
029: * JMoney data storage is implemented in plug-ins. This allows
030: * a choice of methods of data storage. Some data storage implementations
031: * may load the entire database into memory when the datastore is opened.
032: * An example of this type of datastore plug-in is the XML serialized data
033: * storage plug-in. Other plug-ins, however, may only load data on demand.
034: * An example is a plug-in that stores the data in a JDBC database.
035: * The JDBC database plug-in, for example, constructs an <code>Entry</code> object
036: * only when the user requests an account entry list view of the account in
037: * which the <code>Entry</code> occurs.
038: * <P>
039: * In order to support this, the data model implementation classes do not
040: * directly contain references to other classes in the data model.
041: * Instead, they contain a reference to an object that
042: * implements the <code>IObjectKey</code> interface. The
043: * object key implements the <code>getObject</code>
044: * method which returns a reference to the actual extendable
045: * object. This method should be called when and only when
046: * a reference to the property object is required. The <code>getObject</code> method
047: * should be called by the getter for the property.
048: * <P>
049: * This interface is not used for properties that are lists
050: * (regardless of whether the list is a list of objects or
051: * a list of scalar values). List properties use the
052: * <code>IListManager</code> interface.
053: * <P>
054: * This interface is designed to be implemented only by plug-ins
055: * that implement a datastore. Most plug-ins do not need to be
056: * aware of this interface or need to call any of the methods in it.
057: * Plug-ins that implement property sets that contain properties that
058: * reference other data model objects must be aware of this interface.
059: *
060: * @see IListManager
061: * @author Nigel Westbury
062: */
063: public interface IObjectKey {
064: /**
065: * Returns a reference to the actual extendable
066: * object. This method should be called when and only when
067: * a reference to the property object is required. The <code>getObject</code> method
068: * should be called by the getter for the property.
069: * <P>
070: * Implementations of this method may construct the object
071: * every time the method is called. Construction of the object
072: * may require reading data from a database. Users of this method
073: * must therefore be aware that
074: * <LI>
075: * <UL>This method may not be efficient. Users of this method should
076: * therefore cache values returned by this method.
077: * </UL>
078: * <UL>This method may return an object with a different java identity
079: * each time it is called. However, every call of this method on
080: * a given IObjectKey object will return objects that all are
081: * equal when using the <code>equals</code> method.
082: * </UL>
083: * <UL>This method is used when getting property values using the getter methods.
084: * users of getter methods that return references to objects in the data model
085: * must therefore also be aware of the above two points.
086: * </UL>
087: * @return a reference to the actual extendable object
088: */
089: ExtendableObject getObject();
090:
091: /**
092: * Set the given property values in the datastore.
093: * <P>
094: * This method does not update the values in the object
095: * itself. That must be done by the caller after this
096: * method is called. This method may read the old values
097: * from the object itself to determine which values
098: * have changed.
099: *
100: * @param oldValues An object from which the old values of the properties may
101: * be obtained by calling the getter method for each property.
102: * @param newValues An array containing the new property values. The elements
103: * of this array must match one to one the scalar properties of the object
104: * and in the correct order. Intrinsic properties (int, long etc) must
105: * be passed as objects (Integer, Long etc).
106: * @param extensionProperties
107: */
108: // TODO: PropertySet must be of class that extends referenced class
109: void updateProperties(ExtendablePropertySet<?> actualPropertySet,
110: Object[] oldValues, Object[] newValues);
111:
112: /**
113: * Returns the session object. Objects often need access to the session object.
114: * For example, the CapitalAccount constructor sets the currency to the default
115: * currency for the session if a null currency is passed.
116: * <P>
117: * The datastore implementation usually require that the object keys have access
118: * to the session manager. It is therefore very easy to provide the session
119: * through this method, and this saves a lot of code and fields in the
120: * object implementation classes to keep track of the session.
121: * <P>
122: * WARNING: Be very careful about the use of this method.
123: * The session will not be set until it is constructed.
124: * Therefore any code that may be called during the initial
125: * construction of a session may not call this method.
126: * This includes extendable object constructors that are being
127: * called to construct an object store from a datastore.
128: * It does not include the constructor when adding a new object.
129: * As these are the same constructors, this is very confusing.
130: *
131: * @return
132: */
133: Session getSession();
134:
135: /**
136: * @return
137: */
138: DataManager getDataManager();
139:
140: /**
141: * Constructs a list manager that is suitable for managing a list
142: * property in the object represented by this object key.
143: *
144: * @param <E>
145: * @param listAccessor a list property, which must be a property of
146: * the object represented by this object key
147: * @return
148: */
149: <E extends ExtendableObject> IListManager<E> constructListManager(
150: ListPropertyAccessor<E> listAccessor);
151: }
|