001: /***************************************************************
002: * This file is part of the [fleXive](R) project.
003: *
004: * Copyright (c) 1999-2008
005: * UCS - unique computing solutions gmbh (http://www.ucs.at)
006: * All rights reserved
007: *
008: * The [fleXive](R) project is free software; you can redistribute
009: * it and/or modify it under the terms of the GNU General Public
010: * License as published by the Free Software Foundation;
011: * either version 2 of the License, or (at your option) any
012: * later version.
013: *
014: * The GNU General Public License can be found at
015: * http://www.gnu.org/copyleft/gpl.html.
016: * A copy is found in the textfile GPL.txt and important notices to the
017: * license from the author are found in LICENSE.txt distributed with
018: * these libraries.
019: *
020: * This library is distributed in the hope that it will be useful,
021: * but WITHOUT ANY WARRANTY; without even the implied warranty of
022: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
023: * GNU General Public License for more details.
024: *
025: * For further information about UCS - unique computing solutions gmbh,
026: * please see the company website: http://www.ucs.at
027: *
028: * For further information about [fleXive](R), please see the
029: * project website: http://www.flexive.org
030: *
031: *
032: * This copyright notice MUST APPEAR in all copies of the file!
033: ***************************************************************/package com.flexive.shared.interfaces;
034:
035: import com.flexive.shared.configuration.Parameter;
036: import com.flexive.shared.exceptions.FxApplicationException;
037: import com.flexive.shared.exceptions.FxLoadException;
038: import com.flexive.shared.scripting.*;
039:
040: import javax.ejb.Remote;
041: import java.sql.Connection;
042: import java.sql.SQLException;
043: import java.util.List;
044:
045: /**
046: * Scripting engine
047: *
048: * @author Markus Plesser (markus.plesser@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
049: */
050: @Remote
051: public interface ScriptingEngine {
052:
053: /**
054: * Load a scripts code
055: *
056: * @param scriptId requested script
057: * @return code
058: * @throws FxApplicationException on errors
059: */
060: String loadScriptCode(long scriptId) throws FxApplicationException;
061:
062: /**
063: * Get all available information about a script
064: *
065: * @param scriptId id of the requested script
066: * @return FxScriptInfo
067: * @throws FxApplicationException on errors
068: */
069: public FxScriptInfo getScriptInfo(long scriptId)
070: throws FxApplicationException;
071:
072: /**
073: * Get all available information for all existing scripts
074: *
075: *
076: * @return FxScriptInfo
077: * @throws FxApplicationException on errors
078: */
079: public FxScriptInfo[] getScriptInfos()
080: throws FxApplicationException;
081:
082: /**
083: * Update a scripts info
084: *
085: * @param scriptId requested script id
086: * @param event requested script event
087: * @param name new name (or <code>null</code> if unchanged)
088: * @param description new description (or <code>null</code> if unchanged)
089: * @param code the code
090: * @param active if the script is active
091: * @throws FxApplicationException on errors
092: * @see com.flexive.shared.scripting.FxScriptEvent
093: */
094: void updateScriptInfo(long scriptId, FxScriptEvent event,
095: String name, String description, String code, boolean active)
096: throws FxApplicationException;
097:
098: /**
099: * Update script info
100: *
101: * @param scriptInfo the edited script info
102: * @throws com.flexive.shared.exceptions.FxApplicationException on errors
103: */
104: void updateScriptInfo(FxScriptInfoEdit scriptInfo)
105: throws FxApplicationException;
106:
107: /**
108: * Convenience method to update a scripts code
109: *
110: * @param scriptId requested script id
111: * @param code the code
112: * @throws FxApplicationException on errors
113: * @see #updateScriptInfo(long, com.flexive.shared.scripting.FxScriptEvent , String, String, String, boolean)
114: */
115: void updateScriptCode(long scriptId, String code)
116: throws FxApplicationException;
117:
118: /**
119: * Get scripts by their type
120: *
121: * @param scriptEvent requested script event
122: * @return array of id's by type
123: */
124: List<Long> getByScriptType(FxScriptEvent scriptEvent);
125:
126: /**
127: * Create a new script
128: * (newly created scripts are set to active per default).
129: *
130: * @param event script event
131: * @param name (unique) name
132: * @param description description
133: * @param code code
134: * @return FxScriptInfo for the new created script
135: * @throws FxApplicationException on errors
136: * @see com.flexive.shared.scripting.FxScriptEvent
137: */
138: FxScriptInfo createScript(FxScriptEvent event, String name,
139: String description, String code)
140: throws FxApplicationException;
141:
142: /**
143: * Create a new script based on a script from the library
144: * (newly created scripts are set to active per default).
145: * @param event script event
146: * @param libraryname name of the script in the script library
147: * @param name (unique) name
148: * @param description description
149: * @return FxScriptInfo for the new created script
150: * @throws FxApplicationException on errors
151: * @see com.flexive.shared.scripting.FxScriptEvent
152: */
153: FxScriptInfo createScriptFromLibrary(FxScriptEvent event,
154: String libraryname, String name, String description)
155: throws FxApplicationException;
156:
157: /**
158: * Create a new script based on a script from the library
159: * (newly created scripts are set to active per default).
160: *
161: * @param dropName name of the drop to use as repository
162: * @param event script event
163: * @param libraryname name of the script in the script library
164: * @param name (unique) name
165: * @param description description
166: * @return FxScriptInfo for the new created script
167: * @throws FxApplicationException on errors
168: * @see com.flexive.shared.scripting.FxScriptEvent
169: */
170: FxScriptInfo createScriptFromDropLibrary(String dropName,
171: FxScriptEvent event, String libraryname, String name,
172: String description) throws FxApplicationException;
173:
174: /**
175: * Remove a script (will remove all mappings for this script as well)
176: *
177: * @param scriptId id of the script and its mappings to remove
178: * @throws FxApplicationException on errors
179: */
180: void removeScript(long scriptId) throws FxApplicationException;
181:
182: /**
183: * Run a script with the given variable binding
184: *
185: * @param scriptId id of the script to run
186: * @param binding variable binding to use (all bound variables have to be serializable!)
187: * @return script result
188: * @throws FxApplicationException on errors
189: */
190: FxScriptResult runScript(long scriptId, FxScriptBinding binding)
191: throws FxApplicationException;
192:
193: /**
194: * Execute a script
195: *
196: * @param name name of the script, extension is needed to choose interpreter
197: * @param binding bindings to apply
198: * @param code the script code
199: * @return last script evaluation result
200: * @throws FxApplicationException on errors
201: */
202: public FxScriptResult runScript(String name,
203: FxScriptBinding binding, String code)
204: throws FxApplicationException;
205:
206: /**
207: * Get a list containing script extension and script engine info as 2-dimensional String array
208: *
209: * @return list containing script extension and script engine info as 2-dimensional String array
210: * @throws FxApplicationException on errors
211: */
212: public List<String[]> getAvailableScriptEngines()
213: throws FxApplicationException;
214:
215: /**
216: * Run a script
217: *
218: * @param scriptId id of the script to run
219: * @return script result
220: * @throws FxApplicationException on errors
221: */
222: FxScriptResult runScript(long scriptId)
223: throws FxApplicationException;
224:
225: /**
226: * Create a new mapping for assignments with the default FxScriptEvent the script was created with
227: *
228: * @param scriptId id of the script
229: * @param assignmentId id of the assignment
230: * @param active mapping is active?
231: * @param derivedUsage mapping used in derived assignments?
232: * @return the created entry
233: * @throws FxApplicationException on errors
234: */
235: FxScriptMappingEntry createAssignmentScriptMapping(long scriptId,
236: long assignmentId, boolean active, boolean derivedUsage)
237: throws FxApplicationException;
238:
239: /**
240: * Create a new mapping for assignments with with a given FxScriptEvent
241: *
242: * @param scriptEvent FxScriptEvent for this mapping (on create, save, remove, etc.)
243: * @param scriptId id of the script
244: * @param assignmentId id of the assignment
245: * @param active mapping is active?
246: * @param derivedUsage mapping used in derived assignments?
247: * @return the created entry
248: * @throws FxApplicationException on errors
249: */
250: FxScriptMappingEntry createAssignmentScriptMapping(
251: FxScriptEvent scriptEvent, long scriptId,
252: long assignmentId, boolean active, boolean derivedUsage)
253: throws FxApplicationException;
254:
255: /**
256: * Loads all assignment mappings for a specified script
257: *
258: * @param _con the database connection
259: * @param scriptId the script
260: * @return the script mappings
261: * @throws FxLoadException on errors
262: * @throws SQLException on errors
263: */
264: FxScriptMapping loadScriptMapping(Connection _con, long scriptId)
265: throws FxLoadException, SQLException;
266:
267: /**
268: * Create a new mapping for types with the default FxScriptEvent the script was created with
269: *
270: * @param scriptId id of the script
271: * @param typeId id of the type
272: * @param active mapping is active?
273: * @param derivedUsage mapping used in derived types?
274: * @return the created entry
275: * @throws FxApplicationException on errors
276: */
277: FxScriptMappingEntry createTypeScriptMapping(long scriptId,
278: long typeId, boolean active, boolean derivedUsage)
279: throws FxApplicationException;
280:
281: /**
282: * Create a new mapping for types with a given FxScriptEvent
283: *
284: * @param scriptEvent FxScriptEvent for this mapping (on create, save, remove, etc.)
285: * @param scriptId id of the script
286: * @param typeId id of the type
287: * @param active mapping is active?
288: * @param derivedUsage mapping used in derived types?
289: * @return the created entry
290: * @throws FxApplicationException on errors
291: */
292: FxScriptMappingEntry createTypeScriptMapping(
293: FxScriptEvent scriptEvent, long scriptId, long typeId,
294: boolean active, boolean derivedUsage)
295: throws FxApplicationException;
296:
297: /**
298: * Remove a mapping from a script to an assignment (directly mapped, not via inheritance!)
299: *
300: * @param scriptId id of the script
301: * @param assignmentId id of the assignment
302: * @throws FxApplicationException on errors
303: */
304: void removeAssignmentScriptMapping(long scriptId, long assignmentId)
305: throws FxApplicationException;
306:
307: /**
308: * Remove a mapping from a script to an assignment for a specific event
309: * (directly mapped, not via inheritance!)
310: *
311: * @param scriptId id of the script
312: * @param assignmentId id of the assignment
313: * @param event the script event
314: * @throws FxApplicationException on errors
315: */
316: void removeAssignmentScriptMappingForEvent(long scriptId,
317: long assignmentId, FxScriptEvent event)
318: throws FxApplicationException;
319:
320: /**
321: * Remove a mapping from a script to a type (directly mapped, not via inheritance!)
322: *
323: * @param scriptId id of the script
324: * @param typeId id of the type
325: * @throws FxApplicationException on errors
326: */
327: void removeTypeScriptMapping(long scriptId, long typeId)
328: throws FxApplicationException;
329:
330: /**
331: * Remove a mapping from a script to a type (directly mapped, not via inheritance!) for a specific script event
332: *
333: * @param scriptId id of the script
334: * @param typeId id of the type
335: * @param event the script event
336: * @throws FxApplicationException on errors
337: */
338: void removeTypeScriptMappingForEvent(long scriptId, long typeId,
339: FxScriptEvent event) throws FxApplicationException;
340:
341: /**
342: * Update a mapping for assignments
343: *
344: * @param scriptId id of the script
345: * @param assignmentId id of the assignment
346: * @param event the script event
347: * @param active mapping is active?
348: * @param derivedUsage mapping used in derived assignments?
349: * @return the updated entry
350: * @throws FxApplicationException on errors
351: */
352: FxScriptMappingEntry updateAssignmentScriptMappingForEvent(
353: long scriptId, long assignmentId, FxScriptEvent event,
354: boolean active, boolean derivedUsage)
355: throws FxApplicationException;
356:
357: /**
358: * Update a mapping for types
359: *
360: * @param scriptId id of the script
361: * @param typeId id of the type
362: * @param event the script event
363: * @param active mapping is active?
364: * @param derivedUsage mapping used in derived types?
365: * @return the updated entry
366: * @throws FxApplicationException on errors
367: */
368: FxScriptMappingEntry updateTypeScriptMappingForEvent(long scriptId,
369: long typeId, FxScriptEvent event, boolean active,
370: boolean derivedUsage) throws FxApplicationException;
371:
372: /**
373: * Execute run-once scripts.
374: * No exceptions are throws since there is no means of user feedback.
375: * If errors occur, they are written to the logfile.
376: * run-once scripts are only executed once in the lifetime of a division!
377: * consecutive calls have no effect and nothing will be executed!
378: */
379: void executeRunOnceScripts();
380:
381: /**
382: * Execute start up scripts.
383: * No exceptions are throws since there is no means of user feedback.
384: * If errors occur, they are written to the logfile.
385: * start up scripts are only executed once each time the application server is started.
386: * consecutive calls *will* execute start up scripts again!
387: */
388: void executeStartupScripts();
389:
390: /**
391: * Execute run-once scripts for drops.
392: * run-once scripts are only executed once in the lifetime of a division!
393: * consecutive calls have no effect and nothing will be executed!
394: * param will be set to "true" once the scripts are run and will be checked to be "false" prior to run
395: *
396: * @param param boolean parameter to mark scripts as being run
397: * @param dropName name of the drop (WAR archive name without extension)
398: * @throws FxApplicationException if the requested drop is unknown or invalid
399: */
400: void executeDropRunOnceScripts(Parameter<Boolean> param,
401: String dropName) throws FxApplicationException;
402:
403: /**
404: * Execute start up scripts for a specific drop. To be called from a filter or the like.
405: * No exceptions are throws since there is no means of user feedback.
406: * If errors occur, they are written to the logfile.
407: * start up scripts are only executed once each time the application server is started.
408: * consecutive calls *will* execute start up scripts again!
409: *
410: * @param dropName name of the drop (WAR archive name without extension)
411: * @throws FxApplicationException if the requested drop is unknown or invalid
412: */
413: void executeDropStartupScripts(String dropName)
414: throws FxApplicationException;
415: }
|