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 to objects that control a change to the datastore.
027: *
028: * All changes to the datastore must be done thru a datastore
029: * change object.
030: * <P>
031: * There are a number of reasons why changes should be made
032: * thru an IDatastoreChange object, and why plug-ins should not simply
033: * call 'setter' methods, 'add' methods, and 'remove' methods.
034: * <ul>
035: * <li>
036: * If the underlying datastore supports transactions
037: * (using 'transaction' with the meaning usually assumed
038: * in the database community) then each IDatastoreChange object
039: * will correspond to a single transaction in the datastore.
040: * </li>
041: * <li>
042: * By using IDatastoreChange objects, multiple changes may be
043: * consolidated into more efficient updates. For example,
044: * if multiple property values are changed by calling the
045: * setter methods then these can all result in a single
046: * 'update' statement being sent to the database.
047: * </li>
048: * <li>
049: * IDatastoreChange objects manage locks. For example, consider a user
050: * who opens two views that both allow the user to change the
051: * properties of the same account.
052: * Neither view will see changes from the other view until
053: * those changes are committed. This can
054: * cause confusion and cause changes to be lost, if the
055: * user switched back and forth between the two views.
056: * By using IDatastoreChange objects, the second view will not
057: * be able to obtain an IDatastoreChange object and must act
058: * appropriately (for example, by disabling the property
059: * value fields).
060: * </li>
061: * <li>
062: * 'Undo' and 'Redo' support. The 'Undo'/'Redo' feature
063: * keeps a list of the IDatastoreChange objects that performed changes
064: * to the datastore. Every IDatastoreChange object must implement the
065: * <code>undo</code> and <code>redo</code> methods.
066: * </li>
067: * </ul>
068: */
069: public interface IDatastoreChange {
070: /**
071: *
072: * @return The description of the change. This string
073: * is shown to the user by the 'undo' and 'redo'
074: * feature. This description must be localized.
075: */
076: String getDescription();
077:
078: /**
079: * Commits the changes to the datastore. Other views
080: * will see the changes, when this method is called.
081: * <P>
082: * This method also adds this object to the 'undo'/'redo'
083: * list.
084: * <P>
085: * Either <code>commit</code> or <code>rollback</code>
086: * must be called after the changes have been set in
087: * this object. If not, locks will not be released.
088: */
089: void commit();
090:
091: /**
092: * Releases the locks.
093: * <P>
094: * Either <code>commit</code> or <code>rollback</code>
095: * must be called after the changes have been set in
096: * this object. If not, locks will not be released.
097: */
098: void rollback();
099:
100: /**
101: * Undo the change and commit the 'undo' so that other
102: * views see that the change has been 'undone'.
103: */
104: void undo();
105:
106: /**
107: * Redo the change and commit the change so that other
108: * views see the change again.
109: * <P>
110: * In most implementations this method will have an
111: * identical implementation to the <code>commit</code>
112: * method.
113: */
114: void redo();
115: }
|