001: /*
002: * Copyright 2006 Pentaho Corporation. All rights reserved.
003: * This software was developed by Pentaho Corporation and is provided under the terms
004: * of the Mozilla Public License, Version 1.1, or any later version. You may not use
005: * this file except in compliance with the license. If you need a copy of the license,
006: * please go to http://www.mozilla.org/MPL/MPL-1.1.txt. The Original Code is the Pentaho
007: * BI Platform. The Initial Developer is Pentaho Corporation.
008: *
009: * Software distributed under the Mozilla Public License is distributed on an "AS IS"
010: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. Please refer to
011: * the license for the specific language governing your rights and limitations.
012: */
013: /*
014: * Created on Jun 17, 2005
015: *
016: * TODO To change the template for this generated file go to
017: * Window - Preferences - Java - Code Style - Code Templates
018: */
019: package org.pentaho.core.runtime;
020:
021: import org.pentaho.core.audit.IAuditable;
022: import org.pentaho.core.repository.IContentItem;
023: import org.pentaho.core.session.IPentahoSession;
024: import org.pentaho.core.solution.IActionCompleteListener;
025: import org.pentaho.core.solution.IActionResource;
026: import org.pentaho.core.solution.IActionSequence;
027: import org.pentaho.core.solution.IOutputHandler;
028: import org.pentaho.core.ui.IPentahoUrlFactory;
029: import org.pentaho.core.util.IParameterResolver;
030: import org.pentaho.util.logging.ILogger;
031:
032: import java.util.*;
033: import java.io.*;
034:
035: import javax.activation.DataSource;
036:
037: import org.dom4j.*;
038:
039: /**
040: * This interface defines methods and constants that are used during
041: * action execution to resolve parameters, inputs and outputs, resources,
042: * and persist the runtime data. Think of the runtime context as
043: * working storage for the execution of an action.
044: *
045: * @author James Dixon
046: */
047: public interface IRuntimeContext extends IAuditable, ILogger {
048: /**
049: * Unused
050: */
051: public static final String FEEDBACK_OUTPUT = "feedback-output"; //$NON-NLS-1$
052:
053: /**
054: * Indicator of action validation failure
055: */
056: public static final int RUNTIME_CONTEXT_VALIDATE_FAIL = 0;
057:
058: /**
059: * Indicator of action validation success
060: */
061: public static final int RUNTIME_CONTEXT_VALIDATE_OK = 1;
062:
063: /**
064: * Indicates that the parameters for an action were
065: * able to be resolved.
066: */
067: public static final int RUNTIME_CONTEXT_RESOLVE_OK = 2;
068:
069: /**
070: * Indicates that parameters for an action could not
071: * be resolved.
072: */
073: public static final int RUNTIME_CONTEXT_RESOLVE_FAIL = 9;
074:
075: /**
076: * When beginning execution of an action sequence, the
077: * status starts off as not started.
078: */
079: public static final int RUNTIME_STATUS_NOT_STARTED = 3;
080:
081: /**
082: * Indicator that initialization happened successfully
083: */
084: public static final int RUNTIME_STATUS_INITIALIZE_OK = 4;
085:
086: /**
087: * Indicator of initialization failure
088: */
089: public static final int RUNTIME_STATUS_INITIALIZE_FAIL = 8;
090:
091: /**
092: * As an action sequence begins execution, the status is
093: * set to running.
094: */
095: public static final int RUNTIME_STATUS_RUNNING = 5;
096:
097: /**
098: * Indicates that the action executed successfully
099: */
100: public static final int RUNTIME_STATUS_SUCCESS = 6;
101:
102: /**
103: * Indicator of action failure.
104: */
105: public static final int RUNTIME_STATUS_FAILURE = 7;
106:
107: /**
108: * Indicates an invalid instance ID was passed into the execution of an action sequence
109: */
110: public static final int RUNTIME_STATUS_SETUP_FAIL = 10;
111:
112: /**
113: * Currently only used as an indicator that BIRT report specification parameters
114: * could not be read.
115: */
116: public static final int PARAMETERS_FAIL = 1;
117:
118: /**
119: * Currently only used as an indicator that BIRT report specification parameters
120: * could be read properly.
121: */
122: public static final int PARAMETERS_OK = 2;
123:
124: /**
125: * Indicates that parameters are required by an action, and the parameters aren't
126: * available so they need to be prompted for.
127: */
128: public static final int PARAMETERS_UI_NEEDED = 3;
129:
130: /**
131: * Indicates that no parameter prompts are pending.
132: */
133: public static final int PROMPT_NO = 0;
134:
135: /**
136: * Indicates that parameter prompts are pending.
137: */
138: public static final int PROMPT_WAITING = 1;
139:
140: /**
141: * Indicates that we need to prompt immediately for parameters.
142: */
143: public static final int PROMPT_NOW = 2;
144:
145: /**
146: * Returns the unique context identifier. The handle is created during
147: * construction of the <code>RuntimeContext</code> object, and should be
148: * unique down to the date/time of construction. The default form of this
149: * as implemented in <tt>RuntimeContext</tt> includes context- plus the
150: * hashcode and the date/time.
151: * @return the unique handle.
152: * @see RuntimeContext
153: */
154: public String getHandle();
155:
156: /**
157: * During execution of an action sequence, returns the IActionSequence#getTitle().
158: * @return Action sequence title
159: * @see IActionSequence#getSequenceTitle()
160: */
161: public String getActionTitle();
162:
163: /** Forces the runtime to stop processing Actions and return to prompt */
164: public void promptNow();
165:
166: /** Sets the prompt flag but continue processing Actions */
167: public void promptNeeded();
168:
169: /**
170: * Tells if a component is waiting for a prompt
171: *
172: * @return true if a prompt is pending
173: */
174: public boolean isPromptPending();
175:
176: /**
177: * Returns the unique execution instance. This is typically a GUID that can be used to
178: * track the entire execution of an action sequence all the way from beginning to end.
179: * @return unique instance Id
180: */
181: public String getInstanceId();
182:
183: /**
184: * Sets the current action sequence
185: * @param actionSequence The action sequence to validate
186: */
187: public void setActionSequence(IActionSequence actionSequence);
188:
189: public IActionSequence getActionSequence();
190:
191: /**
192: * Validates the action sequence for consistency
193: * @param sequenceName The name of the sequence to validate
194: * @return integer indicating success or failure
195: * @see IRuntimeContext#RUNTIME_CONTEXT_VALIDATE_FAIL
196: * @see IRuntimeContext#RUNTIME_CONTEXT_VALIDATE_OK
197: */
198: public int validateSequence(String sequenceName);
199:
200: /**
201: * Executes the action sequence.
202: * @param listener The listener to be notified when the sequence finishes
203: * @param async Whether the action is synchronous or asynchronous.
204: * @return <code>int</code> indicating success
205: * @see IRuntimeContext#RUNTIME_STATUS_FAILURE
206: * @see IRuntimeContext#RUNTIME_STATUS_SUCCESS
207: */
208: public int executeSequence(IActionCompleteListener listener,
209: boolean async);
210:
211: /**
212: * The Url Factory is used for building URL's that link to this or another application
213: * @return the URL Factory
214: */
215: public IPentahoUrlFactory getUrlFactory();
216:
217: /**
218: * @return The name of the solution holding the currently executing action sequence
219: */
220: public String getSolutionName();
221:
222: /**
223: * @return The path within the solution holding the currently executing action sequence
224: */
225: public String getSolutionPath();
226:
227: /**
228: * @return The component in the action seqeuence that's being executed
229: */
230: public String getCurrentComponentName();
231:
232: /**
233: * @return The session that started execution of the current action sequence
234: */
235: public IPentahoSession getSession();
236:
237: /**
238: * Writes a message to the audit log.
239: * @param messageType Message type as defined in <tt>MessageTypes</tt>
240: * @param message Message to appear in the log
241: * @param value Value of an object to be logged.
242: * @param duration For time-tracked execution paths, indicates the duration the task took
243: * @see org.pentaho.core.audit.IAuditEntry
244: * @see IAuditable
245: * @see org.pentaho.core.audit.MessageTypes
246: */
247: public void audit(String messageType, String message, String value,
248: long duration);
249:
250: /**
251: * Returns the named input parameter. This will search amongst all the input parameter providers
252: * (<tt>IParameterProvider</tt>) in order until it finds the input parameter and returns it.
253: * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
254: * <code>null</code>
255: * @param name The name of the parameter to get
256: * @return The parameter
257: * @see org.pentaho.core.solution.IParameterProvider
258: */
259: public IActionParameter getInputParameter(String name);
260:
261: /**
262: * Returns the named output parameter. This will search amongst all the output parameter providers
263: * (<tt>IParameterProvider</tt>) in order until it finds the output parameter and returns it.
264: * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
265: * <code>null</code>
266: * @param name The name of the parameter to get
267: * @return The requested parameter
268: * @see org.pentaho.core.solution.IParameterProvider
269: */
270: public IActionParameter getOutputParameter(String name);
271:
272: /**
273: * Gets the named resource definition from the executing action sequence.
274: * Throws a <tt>NullPointerException</tt> if the resource is not found. This method never returns
275: * <code>null</code>
276: * @param name The named resource to get
277: * @return The resource if it exists.
278: * @see IActionResource
279: */
280: public IActionResource getResourceDefintion(String name);
281:
282: /**
283: * Gets the value of the specified input parameter.
284: * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
285: * <code>null</code>
286: * @param name The named parameter to retrieve
287: * @return The <tt>IActionParameter#getValue()</tt>
288: * @see IActionParameter
289: */
290: public Object getInputParameterValue(String name);
291:
292: /**
293: * Gets the value of the specified input parameter as a <code>String</code>.
294: * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
295: * <code>null</code>
296: * @param name The named parameter to retrieve
297: * @return The <tt>IActionParameter#getStringValue()</tt>
298: * @see IActionParameter
299: */
300: public String getInputParameterStringValue(String name);
301:
302: /**
303: * Gets the named resource as an <tt>InputStream</tt>. This is just a utility
304: * method that interfaces to <tt>ISolutionRepository</tt>
305: * @param actionResource The resource to get from the <code>SolutionRepository</code>
306: * @return The <code>InputStream</code> that contains the resource.
307: * @throws FileNotFoundException
308: * @see ISolutionRepository#getResourceInputStream(IActionResource)
309: */
310: public InputStream getResourceInputStream(
311: IActionResource actionResource)
312: throws FileNotFoundException;
313:
314: /**
315: * Gets the named resource as a <tt>DataSource</tt>. This is just a utility
316: * method that interfaces to <tt>ISolutionRepository</tt>
317: * @param actionResource The resource to get from the <code>SolutionRepository</tt>
318: * @return The <code>DataSource</code>
319: * @throws FileNotFoundException
320: * @see ISolutionRepository#getResourceDataSource(IActionResource)
321: */
322: public DataSource getResourceDataSource(
323: IActionResource actionResource)
324: throws FileNotFoundException;
325:
326: /**
327: * Gets the named resource as a <tt>Reader</tt>. This is just a utility
328: * method that interfaces to <tt>ISolutionRepository</tt>
329: * @param actionResource The resource to get from the <code>SolutionRepository</tt>
330: * @return The <code>Reader</code>
331: * @see ISolutionRepository#getResourceReader(IActionResource)
332: */
333: public Reader getResourceReader(IActionResource actionParameter)
334: throws IOException;
335:
336: /**
337: * Gets the named resource as a <tt>String</tt>. This is just a utility
338: * method that interfaces to <tt>ISolutionRepository</tt>
339: * @param actionResource The resource to get from the <code>SolutionRepository</tt>
340: * @return The <code>String</code>
341: * @see ISolutionRepository#getResourceAsString(IActionResource)
342: */
343: public String getResourceAsString(IActionResource actionParameter)
344: throws IOException;
345:
346: /**
347: * Gets the named resource as a <tt>Document</tt>. This is just a utility
348: * method that interfaces to <tt>ISolutionRepository</tt>
349: * @param actionResource The resource to get from the <code>SolutionRepository</tt>
350: * @return The <code>DataSource</code>
351: * @see ISolutionRepository#getResourceAsDocument(IActionResource)
352: */
353: public Document getResourceAsDocument(
354: IActionResource actionParameter) throws IOException;
355:
356: /**
357: * Sets the value of a named output parameter
358: * @param name The name of the output parameter
359: * @param output The value to set the output parameter to
360: */
361: public void setOutputValue(String name, Object output);
362:
363: /**
364: * Adds a parameter to the current inputs. A component can be use this to create parameters for internal use or for new outputs.
365: * @param name The name of the temporary parameter
366: * @param output The value to set the temporary parameter to
367: */
368: public void addTempParameter(String name, IActionParameter output);
369:
370: /**
371: * Returns an output stream for writing.
372: * @param outputName The name of the output
373: * @param mimeType The mime type of the output
374: * @param extension The file extension of the output
375: * @return OutputStream for writing to
376: */
377: public IContentItem getOutputItem(String outputName,
378: String mimeType, String extension);
379:
380: /**
381: * Returns an input stream from an input parameter, if the input parameter is
382: * a content item.
383: * @param parameterName The name of the parameter
384: * @return An InputStream from the content item
385: */
386: public InputStream getInputStream(String parameterName);
387:
388: /**
389: * Get's the content item associated with the parameter, and returns the content item's
390: * datasource
391: * @param parameterName The name of the parameter
392: * @return The DataSource from the Content Item
393: * @see IContentItem#getDataSource()
394: */
395: public DataSource getDataSource(String parameterName);
396:
397: /**
398: * @return a <tt>Set</tt> containing all the inputs in the current action.
399: */
400: public Set getInputNames();
401:
402: /**
403: * @return a <tt>Set</tt> containing the resource names in the action
404: */
405: public Set getResourceNames();
406:
407: /**
408: * @return a <tt>Set</tt> containing the output names in the current action
409: */
410: public Set getOutputNames();
411:
412: /**
413: * Does parameter substitution on the input string, searching for all parameter declarations in the input
414: * string, and substituting the value from the matching input parameter. In other words, it replaces
415: * {REGION} with the value of the input parameter called REGION.
416: * @param format The string containing possible parameter references
417: * @return String with parameters resolved.
418: */
419: public String applyInputsToFormat(String format);
420:
421: /**
422: * Does parameter substitution on the input string, searching for all parameter declarations in the input
423: * string, and substituting the value from the matching input parameter. In other words, it replaces
424: * {REGION} with the value of the input parameter called REGION.
425: * @param format The string containing possible parameter references
426: * @param Resolver for parameters for overriding behavior
427: * @return String with parameters resolved.
428: */
429: public String applyInputsToFormat(String format,
430: IParameterResolver resolver);
431:
432: /**
433: * Adds an input parameter to the list of all inputs for the action sequence
434: * @param name The name of the parameter (the key to the parameter map)
435: * @param param The parameter to add
436: * @see IActionParameter
437: */
438: public void addInputParameter(String name, IActionParameter param);
439:
440: /**
441: * @return true if the current output device allows
442: * user feedback (i.e. parameter input forms)
443: */
444: public boolean feedbackAllowed();
445:
446: /**
447: * Interfaces to the current output handler to get the content item
448: * that is handling feedback (i.e. parameter input forms)
449: * @return the Content Item for user input
450: * @see IContentItem
451: * @see IOutputHandler
452: */
453: public IContentItem getFeedbackContentItem();
454:
455: /**
456: * Interfaces to the current output handler to get the content item
457: * that describes the output from this request's component execution.
458: * @return The content item for output
459: * @see IContentItem
460: * @see IOutputHandler
461: */
462: public IContentItem getOutputContentItem(String mimeType);
463:
464: /**
465: * Interfaces to the current output handler to get the named content item
466: * from this request's component execution.
467: * @param outputName the name of the output
468: * @return The requested content item
469: * @see IContentItem
470: * @see IOutputHandler
471: */
472: public IContentItem getOutputContentItem(String outputName,
473: String mimeType);
474:
475: /**
476: * Returns a url to the passed in content item that can be used to retrieve
477: * the content.
478: *
479: * @param parameterName
480: * the parameter name of the content
481: * @return a string representing the URL or null if the name is not a
482: * content item or is not a valid name.
483: */
484: public String getContentUrl(IContentItem contentItem);
485:
486: /**
487: * Generates a parameter acquisition form for required
488: * parameters. This writes directly to the output stream
489: * provided by the output handler.
490: * @throws IOException
491: * @see IOutputHandler
492: */
493: public void sendFeedbackForm() throws IOException;
494:
495: /**
496: * @deprecated
497: *
498: * Adds a feedback parameter for prompts based on an Action Parameter. Uses
499: * the Selections defined in the Action Parameter for the options and sets
500: * the default to the current value
501: *
502: * @param actionParam
503: * The Action Parameter to use as the model for the prompt
504: */
505: public void createFeedbackParameter(IActionParameter actionParam);
506:
507: /**
508: * Adds a feedback parameter (essentially a form input field) for a
509: * required input.
510: * @param selMap Maps <code>IPentahoResultSet</code> objects to selection objects
511: * @param fieldName Name of the form field
512: * @param defaultValues default values for the input field
513: * @see SelectionMapper
514: */
515: public void createFeedbackParameter(SelectionMapper selMap,
516: String fieldName, Object defaultValues);
517:
518: /**
519: * Adds a feedback parameter (essentially a form input field) for a
520: * required input.
521: * @param selMap Maps <code>IPentahoResultSet</code> objects to selection objects
522: * @param fieldName Name of the form field
523: * @param defaultValues default values for the input field
524: * @param optional specifies if the feedback parameter is required or not
525: * @see SelectionMapper
526: */
527: public void createFeedbackParameter(SelectionMapper selMap,
528: String fieldName, Object defaultValues, boolean optional);
529:
530: /**
531: * Adds a scalar feedback parameter
532: * @param fieldName Name of the input field
533: * @param displayName display name of the input field
534: * @param hint Fly-over hint for the input field
535: * @param defaultValue Default value for the input field
536: * @param visible Whether the input field is visible or not
537: * @see XForm
538: */
539: public void createFeedbackParameter(String fieldName,
540: String displayName, String hint, Object defaultValue,
541: boolean visible);
542:
543: /**
544: * Adds a scalar feedback parameter
545: * @param fieldName Name of the input field
546: * @param displayName display name of the input field
547: * @param hint Fly-over hint for the input field
548: * @param defaultValue Default value for the input field
549: * @param visible Whether the input field is visible or not
550: * @param optional specifies if the feedback parameter is required or not
551: * @see XForm
552: */
553: public void createFeedbackParameter(String fieldName,
554: String displayName, String hint, Object defaultValue,
555: boolean visible, boolean optional);
556:
557: /**
558: * Creates a feedback parameter that uses a list for the values
559: * @param fieldName The name of the field
560: * @param displayName Display name
561: * @param hint Fly-over hint for the input field
562: * @param defaultValues Default value of the input field
563: * @param values List of values
564: * @param dispNames Map of display names
565: * @param displayStyle how to display the control
566: * @see XForm
567: */
568: public void createFeedbackParameter(String fieldName,
569: String displayName, String hint, Object defaultValues,
570: List values, Map dispNames, String displayStyle);
571:
572: /**
573: * Creates a feedback parameter that uses a list for the values
574: * @param fieldName The name of the field
575: * @param displayName Display name
576: * @param hint Fly-over hint for the input field
577: * @param defaultValues Default value of the input field
578: * @param values List of values
579: * @param dispNames Map of display names
580: * @param displayStyle how to display the control
581: * @parm optional specifies if the feedback parameter is required or not
582: * @see XForm
583: */
584: public void createFeedbackParameter(String fieldName,
585: String displayName, String hint, Object defaultValues,
586: List values, Map dispNames, String displayStyle,
587: boolean optional);
588:
589: /**
590: * @return the current status of execution
591: */
592: public int getStatus();
593:
594: /**
595: * @return List of messages saved up during execution. This is used to provide
596: * failure feedback to the user.
597: */
598: public List getMessages();
599:
600: /**
601: * Creates a new runtime context that is a child of this instance
602: *
603: * @param persisted
604: * Should the runtime data be persisted
605: * @return Instance id of the new RuntimeContext
606: */
607: public String createNewInstance(boolean persisted);
608:
609: /**
610: * Creates a new runtime context that is a child of this instance and sets
611: * attributes of the runtime data from the parameter Map
612: *
613: * @param persisted
614: * Should the runtime data be persisted
615: * @param parameters
616: * parameters for the new instance
617: * @return Instance id of the new RuntimeContext
618: */
619: public String createNewInstance(boolean persisted, Map parameters);
620:
621: /**
622: * Creates a new runtime context that is a child of this instance and sets
623: * attributes of the runtime data from the parameter Map, and can
624: * optionally cause the new instance to be forcibly written to the
625: * underlying persistence mechanism.
626: *
627: * @param persisted
628: * Should the runtime data be persisted
629: * @param parameters
630: * parameters for the new instance
631: * @param forceImmediateWrite
632: * if true, will call the new runtime element's forceSave method
633: * before returning.
634: * @return Instance id of the new RuntimeContext
635: */
636: public String createNewInstance(boolean persisted, Map parameters,
637: boolean forceImmediateWrite);
638:
639: public void dispose();
640:
641: /**
642: * Sets the xsl file to be used to generate the parameter page for the
643: * current component. The parameter should be a full path from the solution
644: * root starting with a /, or it should be a path relative to the directory
645: * of the current action sequence.
646: *
647: * @param xsl
648: * The name of the XSL file
649: */
650: public void setParameterXsl(String xsl);
651:
652: /**
653: * Sets the target window that the content will be displayed in. This name
654: * is used at the target in an Window.open() javascript call made when the
655: * submit button on the parameter page is clicked.
656: *
657: * @param target
658: * Window name
659: */
660: public void setParameterTarget(String target);
661:
662: /**
663: * Forces the immediate write of runtime data to underlying persistence
664: * mechanism. In the case of using Hibernate for the runtime data
665: * persistence, this works out to a call to HibernateUtil.flush().
666: */
667: public void forceSaveRuntimeData();
668:
669: /**
670: * Gets the output type prefered by the handler. Values are defined in
671: * org.pentaho.core.solution.IOutputHander and are OUTPUT_TYPE_PARAMETERS,
672: * OUTPUT_TYPE_CONTENT, or OUTPUT_TYPE_DEFAULT
673: *
674: * @return Output type
675: */
676: public int getOutputPreference();
677:
678: /**
679: * Sets the output handler for the runtime context
680: *
681: * @param outputHandler
682: * The output handler
683: *
684: */
685: public void setOutputHandler(IOutputHandler outputHandler);
686:
687: /**
688: * Sets the default prompt status PROMPT_NO, PROMPT_WAITING, PROMPT_NOW
689: * @param status
690: */
691: public void setPromptStatus(int status);
692: }
|