001: /*
002: * The contents of this file are subject to the terms of the Common Development
003: * and Distribution License (the License). You may not use this file except in
004: * compliance with the License.
005: *
006: * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
007: * or http://www.netbeans.org/cddl.txt.
008: *
009: * When distributing Covered Code, include this CDDL Header Notice in each file
010: * and include the License file at http://www.netbeans.org/cddl.txt.
011: * If applicable, add the following below the CDDL Header, with the fields
012: * enclosed by brackets [] replaced by your own identifying information:
013: * "Portions Copyrighted [year] [name of copyright owner]"
014: *
015: * The Original Software is NetBeans. The Initial Developer of the Original
016: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
017: * Microsystems, Inc. All Rights Reserved.
018: */
019:
020: package org.netbeans.modules.bpel.model.api;
021:
022: import java.util.concurrent.Callable;
023:
024: import org.netbeans.modules.bpel.model.api.events.ChangeEventListener;
025: import org.netbeans.modules.bpel.model.api.support.UniqueId;
026: import org.netbeans.modules.xml.xam.Model;
027:
028: /**
029: * This interface is start point for BPEL model access. It contain root element -
030: * process that correspond to process in BPEL file. One should keep reference to
031: * this interface instead of keeping reference to process element, because
032: * reference to process element could mutate ( it is up to implementation ).
033: *
034: * @author ads
035: */
036: public interface BpelModel extends Model<BpelEntity> {
037:
038: /**
039: * This is pseudo property for event that fired when state of OM is changed.
040: */
041: String STATE = "<state>"; // NOI18N
042:
043: /**
044: * @return reference to root of BPEL - process.
045: */
046: Process getProcess();
047:
048: /**
049: * @return builder for BPEL elements.
050: */
051: BPELElementsBuilder getBuilder();
052:
053: /**
054: * Returns entity by its unique id.
055: *
056: * @param id
057: * id of entity.
058: * @return entity by its id.
059: */
060: BpelEntity getEntity(UniqueId id);
061:
062: /**
063: * Accessor to root bpel process element that has different
064: * version from currently supported.
065: * Please note that this is only read-only element.
066: * You should not try to change it in any way.
067: * This method will return each time new instance of such
068: * root element. This method will return null if
069: * bpel process has correct namespace or not well formed ( in terms of XML ).
070: *
071: * @return OM root element that correspond to BPEL process with
072: * different version if any.
073: */
074: AnotherVersionBpelProcess getAnotherVersionProcess();
075:
076: /**
077: *
078: */
079: boolean canExtend(ExtensibleElements extensible,
080: Class<? extends ExtensionEntity> extensionType);
081:
082: /**
083: * Add change listener which will receive events for any element in the
084: * underlying model.
085: *
086: * Listener adds to model as weak reference.
087: * So one needs to care about keeping reference to listener somehere
088: * till it used and need to get events from model.
089: * If one will use anonymous class for adding then it will never get
090: * events.
091: * You should use method removePropertyChangeListener when listener is already not
092: * needed. For using this method you should keep reference to created listener.
093: * If you cannot use method removePropertyChangeListener then probably
094: * you will never get events from model because you don't keep
095: * reference to listener and it could be collected by GC in any time.
096: *
097: * @param listener
098: * listener for add.
099: */
100: void addEntityChangeListener(ChangeEventListener listener);
101:
102: /**
103: * Removes change listener from model.
104: *
105: * @param listener
106: * listener for remove.
107: */
108: void removeEntityChangeListener(ChangeEventListener listener);
109:
110: // /**
111: // * Add undoable listener to model.
112: // *
113: // * @param listener Undoable listener for addition.
114: // */
115: //
116: // void addUndoableEditListener( UndoableEditListener listener );
117: //
118: // /**
119: // * Removes undoable listener from model.
120: // *
121: // * @param listener Undoable listener for removal.
122: // */
123: // void removeUndoableEditListener( UndoableEditListener listener );
124:
125: /**
126: * This method should be used for executing group of calls to model as
127: * atomic action. Placing <code>action</code> in this method guarantee
128: * that model will not be affected via another threads
129: * in process of execution this action.
130: *
131: * Changes in model that represented by <code>action</code>
132: * will be executed synchronously. It means method will end
133: * only after all calls to model inside <code>action</code>
134: * would be executed.
135: *
136: * All model methods getXXX, setXX, addXX, etc. also atomic.
137: * If you need just get value or set new value in model you don't
138: * need to call this method. Each this action will be synchronized.
139: * You need to use this method when you need to perform many actions
140: * one depends from another. In this case value that you get in one action
141: * could be not valid for next action with model.
142: *
143: * @param <V> type for return value.
144: * @param action group of calls to model.
145: * @param source this is object that will be set as source
146: * for events that will be fired by model as result of this action.
147: * It could be used for distinguishing various consumers of model.
148: * Could be equall to null. If it equals to null then source of
149: * event will be set to Thread.currentThread().
150: *
151: * One should not put "sync" method inside <code>invoke()</code>
152: * or in transaction that started with <code>startTransaction()</code>.
153: * Otherwise "sync" will no have any effect. OM consider
154: * starting transaction as starting mutation and
155: * in this case "sync" doesn't have sense.
156: *
157: * @return return value from action.
158: * @throws Exception {@link Exception} exception that could be thrown by <code>action</code>
159: */
160: <V> V invoke(Callable<V> action, Object source) throws Exception;
161:
162: /**
163: * This method execute command <code>run</code> inside read lock on OM
164: * obtained. You should never try mutate OM inside this command <code>run</code>.
165: * Otherwise you will get InvalidaStateException.
166: * @param run command for execution
167: */
168: void invoke(Runnable run);
169:
170: /**
171: * Finds Bpel element on the specified position.
172: * @param i Position in NbDocument.
173: * @return Entity on the position if any.
174: */
175: BpelEntity findElement(int i);
176:
177: }
|