001: // THIS SOFTWARE IS PROVIDED BY SOFTARIS PTY.LTD. AND OTHER METABOSS
002: // CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
003: // BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
004: // FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTARIS PTY.LTD.
005: // OR OTHER METABOSS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
006: // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
007: // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
008: // OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
009: // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
010: // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
011: // EVEN IF SOFTARIS PTY.LTD. OR OTHER METABOSS CONTRIBUTORS ARE ADVISED OF THE
012: // POSSIBILITY OF SUCH DAMAGE.
013: //
014: // Copyright 2000-2005 © Softaris Pty.Ltd. All Rights Reserved.
015: package com.metaboss.sdlctools.models;
016:
017: import java.util.Collection;
018:
019: import javax.jmi.reflect.RefObject;
020:
021: /** Represents the interface for the model assistant component.
022: * Model assistant is a component which can be installed to look after
023: * certain aspects of the model. It can perform following tasks
024: * <UL>
025: * <LI>Validate model and produce list of error mesages describing what is wrong with the model from the point of view of this particular assistant.
026: * Validation is expected to be implemented in body of the verifyConstraints() method. Note that
027: * each assistant should only verify "own" constraints and not general model ones. If due to general model errors
028: * assistant is unable to even check "own" constraints - verifyConstraints() method should just return quetly.</LI>
029: * <LI>Attempt to correct the errors in the model. This is expected to be implemented in body of
030: * the rectifyModel() method.</LI>
031: * <LI>Autocomplete creation, deletion or modification of model objects so the relationships this assitant is looking after remain valid.
032: * Autocompletion is expected to be implemented in bodies of the onModelElement.......() methods. These methods are
033: * invoked by ModelRepository at the time when change is taking place while repository is still in transaction. Therefore
034: * all autocompletion changes to the model will be a part of the same transaction and will be rolled back together with
035: * original changes if required.</LI>
036: * </UL>
037: *
038: */
039: public interface ModelAssistant {
040: /** Naming URL of the component */
041: public static final String COMPONENT_URL = "component:/com.metaboss.sdlctools.models.ModelAssistant";
042:
043: /** The prefix assistants use to form an owner identifier name of the elements they own.
044: * Normally model element owner identifier will consist of <thisprefix><assistant package namegt; */
045: public static final String OWNER_IDENTIFIER_PRREFIX = "assistant:/";
046:
047: /** This interface defines the link from assistant to the model actions logging mechanism.
048: * If assistant has done some change to the model - it has to use 'info' level to report it.
049: * If assistant have noticed something not right, but still managed to do all necessaary changes - the 'warning' level must be used.
050: * If assistant have failed to do something because of broken model - it should use 'error' level.
051: * Note that all other 'technical' logging (e.g.java exceptions etc) should go to the normal platform logging */
052: public interface ModelActionsLogger {
053: /** If assistant has done some change to the model - it has to use 'info' level to report it.
054: * @param pModelName - the name of the model this message is about
055: * @param pMessage - the message */
056: public void info(String pModelName, String pMessage);
057:
058: /** If assistant have noticed something not right, but still managed to do all necessaary changes - the 'warning' level must be used.
059: * @param pModelName - the name of the model this message is about
060: * @param pMessage - the message */
061: public void warn(String pModelName, String pMessage);
062:
063: /** If assistant have failed to do something because of broken model - it should use 'error' level.
064: * @param pModelName - the name of the model this message is about
065: * @param pMessage - the message */
066: public void error(String pModelName, String pMessage);
067: }
068:
069: /** Assign this Assistant to look after a particular model.
070: * Each assistant can only look after one model at a time, but any number of instances of assistants of the same type
071: * may be created as needed (e.g. in case number of instances of the same model have been loaded)
072: * @param pModelName - the name of the model this assistant needs to look after */
073: public void assignToModel(String pModelName)
074: throws ModelRepositoryException;
075:
076: /** Relieve this Assistant from looking after the model
077: * @param pModelName - the name of the model this assistant needs to stop looking after */
078: public void dismissFromModel(String pModelName)
079: throws ModelRepositoryException;
080:
081: /** Assign the actions loger to this assistantis Assistant to look after a particular model.
082: * @param pModelName - the name of the model this logger is assigned to
083: * @param pModelActionsLogger - the logger to use. null passed here will switch logging off */
084: public void setActionsLogger(String pModelName,
085: ModelActionsLogger pModelActionsLogger)
086: throws ModelRepositoryException;
087:
088: /** This method verifies model constraints and returns collection of exceptions.
089: * It is only supposed to verify constraints "owned" by this assistant
090: * @param pModelName - the name of the model to verify constraints on */
091: public Collection verifyConstraints(String pModelName)
092: throws ModelRepositoryException;
093:
094: /** This method attempts to rectify the model. It is only supposed to rectify features "owned"
095: * by this assistant. In case if model is not good enough for this assistant to fix
096: * its own stuff - assistant should quietly exit. Subsequent model validation will pick up errors
097: * @param pModelName - the name of the model to rectify */
098: public void rectifyModel(String pModelName)
099: throws ModelRepositoryException;
100:
101: /** This method is called when ModelElement is being deleted. Model
102: * is in transaction at the time and any change performed here may
103: * be rolled back if transaction is not committed
104: * @param pModelName - the name of the model where action is taking place
105: * @param pModelElementToBeDeleted the element being deleted */
106: public void onModelElementBeingDeleted(String pModelName,
107: RefObject pModelElementToBeDeleted)
108: throws ModelRepositoryException;
109:
110: /** This method is called when ModelElement is being created. Model
111: * is in transaction at the time and any change performed here may
112: * be rolled back if transaction is not committed
113: * @param pModelName - the name of the model where action is taking place
114: * @param pModelElementJustCreated the element being created */
115: public void onModelElementJustCreated(String pModelName,
116: RefObject pModelElementJustCreated)
117: throws ModelRepositoryException;
118:
119: /** This method is called when attribute of the ModelElement has been modified.
120: * Model is in transaction at the time and any change performed here may
121: * be rolled back if transaction is not committed
122: * @param pModelName - the name of the model where action is taking place
123: * @param pModelElementBeingUpdated the element being updated
124: * @param pAttributeName the name of the attribute being updated
125: * @param pOldAttributeValue - the old value of the attribute. May be null if attribute had no value before
126: * @param pNewAttributeValue - the new value of the attribute. May be null if attribute is being cleared */
127: public void onModelElementAttributeBeingUpdated(String pModelName,
128: RefObject pModelElementBeingUpdated, String pAttributeName,
129: Object pOldAttributeValue, Object pNewAttributeValue)
130: throws ModelRepositoryException;
131:
132: /** This method is called when reference of the ModelElement has been modified.
133: * Model is in transaction at the time and any change performed here may
134: * be rolled back if transaction is not committed
135: * @param pModelName - the name of the model where action is taking place
136: * @param pModelElementBeingUpdated the element being updated
137: * @param pReferenceName the name of the reference being updated
138: * @param pReferencedModelElementToRemove - the old referenced element to be removed. May be null if nothing is being removed
139: * @param pReferencedModelElementToAdd - the new referenced element to be added. May be null if nothing is being added */
140: public void onModelElementReferenceBeingUpdated(String pModelName,
141: RefObject pModelElementBeingUpdated, String pReferenceName,
142: RefObject pReferencedModelElementToRemove,
143: RefObject pReferencedModelElementToAdd)
144: throws ModelRepositoryException;
145: }
|