IRuntimeContext


1   /*
2    * Copyright 2006 Pentaho Corporation.  All rights reserved. 
3    * This software was developed by Pentaho Corporation and is provided under the terms 
4    * of the Mozilla Public License, Version 1.1, or any later version. You may not use 
5    * this file except in compliance with the license. If you need a copy of the license, 
6    * please go to http://www.mozilla.org/MPL/MPL-1.1.txt. The Original Code is the Pentaho 
7    * BI Platform.  The Initial Developer is Pentaho Corporation.
8    *
9    * Software distributed under the Mozilla Public License is distributed on an "AS IS" 
10   * basis, WITHOUT WARRANTY OF ANY KIND, either express or  implied. Please refer to 
11   * the license for the specific language governing your rights and limitations.
12  */
13  /*
14   * Created on Jun 17, 2005
15   *
16   * TODO To change the template for this generated file go to
17   * Window - Preferences - Java - Code Style - Code Templates
18   */
19  package org.pentaho.core.runtime;
20  
21  import org.pentaho.core.audit.IAuditable;
22  import org.pentaho.core.repository.IContentItem;
23  import org.pentaho.core.session.IPentahoSession;
24  import org.pentaho.core.solution.IActionCompleteListener;
25  import org.pentaho.core.solution.IActionResource;
26  import org.pentaho.core.solution.IActionSequence;
27  import org.pentaho.core.solution.IOutputHandler;
28  import org.pentaho.core.ui.IPentahoUrlFactory;
29  import org.pentaho.core.util.IParameterResolver;
30  import org.pentaho.util.logging.ILogger;
31  
32  import java.util.*;
33  import java.io.*;
34  
35  import javax.activation.DataSource  ;
36  
37  import org.dom4j.*;
38  
39  /**
40   * This interface defines methods and constants that are used during
41   * action execution to resolve parameters, inputs and outputs, resources,
42   * and persist the runtime data. Think of the runtime context as
43   * working storage for the execution of an action.
44   * 
45   * @author James Dixon
46   */
47  public interface IRuntimeContext extends IAuditable, ILogger {
48      /**
49       * Unused
50       */
51      public static final String   FEEDBACK_OUTPUT = "feedback-output"; //$NON-NLS-1$
52      /**
53       * Indicator of action validation failure
54       */
55      public static final int RUNTIME_CONTEXT_VALIDATE_FAIL = 0;
56      /**
57       * Indicator of action validation success
58       */
59      public static final int RUNTIME_CONTEXT_VALIDATE_OK = 1;
60      /**
61       * Indicates that the parameters for an action were
62       * able to be resolved.
63       */
64      public static final int RUNTIME_CONTEXT_RESOLVE_OK = 2;
65      /**
66       * Indicates that parameters for an action could not
67       * be resolved.
68       */
69      public static final int RUNTIME_CONTEXT_RESOLVE_FAIL = 9;
70      /**
71       * When beginning execution of an action sequence, the
72       * status starts off as not started.
73       */
74      public static final int RUNTIME_STATUS_NOT_STARTED = 3;
75      /**
76       * Indicator that initialization happened successfully
77       */
78      public static final int RUNTIME_STATUS_INITIALIZE_OK = 4;
79      /**
80       * Indicator of initialization failure
81       */
82      public static final int RUNTIME_STATUS_INITIALIZE_FAIL = 8;
83      /**
84       * As an action sequence begins execution, the status is
85       * set to running.
86       */
87      public static final int RUNTIME_STATUS_RUNNING = 5;
88      /**
89       * Indicates that the action executed successfully
90       */
91      public static final int RUNTIME_STATUS_SUCCESS = 6;
92      /**
93       * Indicator of action failure.
94       */
95      public static final int RUNTIME_STATUS_FAILURE = 7;
96      /**
97       * Indicates an invalid instance ID was passed into the execution of an action sequence
98       */
99      public static final int RUNTIME_STATUS_SETUP_FAIL = 10;
100     /**
101      * Currently only used as an indicator that BIRT report specification parameters
102      * could not be read.
103      */
104     public static final int PARAMETERS_FAIL = 1;
105     /**
106      * Currently only used as an indicator that BIRT report specification parameters
107      * could be read properly.
108      */
109     public static final int PARAMETERS_OK = 2;
110     /**
111      * Indicates that parameters are required by an action, and the parameters aren't
112      * available so they need to be prompted for.
113      */
114     public static final int PARAMETERS_UI_NEEDED = 3;
115     /**
116      * Indicates that no parameter prompts are pending.
117      */
118     public static final int PROMPT_NO = 0;
119     /**
120      * Indicates that parameter prompts are pending.
121      */
122     public static final int PROMPT_WAITING = 1;
123     /**
124      * Indicates that we need to prompt immediately for parameters.
125      */
126     public static final int PROMPT_NOW = 2;
127 
128     /**
129      * Returns the unique context identifier. The handle is created during
130      * construction of the <code>RuntimeContext</code> object, and should be
131      * unique down to the date/time of construction. The default form of this
132      * as implemented in <tt>RuntimeContext</tt> includes context- plus the
133      * hashcode and the date/time.
134      * @return the unique handle.
135      * @see RuntimeContext
136      */
137     public String   getHandle();
138     
139     /**
140      * During execution of an action sequence, returns the IActionSequence#getTitle().
141      * @return Action sequence title
142      * @see IActionSequence#getSequenceTitle()
143      */
144     public String   getActionTitle();
145 
146     /** Forces the runtime to stop processing Actions and return to prompt */
147     public void promptNow();
148 
149     /** Sets the prompt flag but continue processing Actions */
150     public void promptNeeded();
151 
152     /**
153      * Tells if a component is waiting for a prompt
154      * 
155      * @return true if a prompt is pending
156      */
157     public boolean isPromptPending();
158 
159     /**
160      * Returns the unique execution instance. This is typically a GUID that can be used to
161      * track the entire execution of an action sequence all the way from beginning to end.
162      * @return unique instance Id
163      */
164     public String   getInstanceId();
165 
166     /**
167      * Sets the current action sequence 
168      * @param actionSequence The action sequence to validate
169      */
170     public void setActionSequence(IActionSequence actionSequence);
171     
172     /**
173      * Validates the action sequence for consistency
174      * @param sequenceName The name of the sequence to validate
175      * @return integer indicating success or failure
176      * @see IRuntimeContext#RUNTIME_CONTEXT_VALIDATE_FAIL
177      * @see IRuntimeContext#RUNTIME_CONTEXT_VALIDATE_OK
178      */
179     public int validateSequence(String   sequenceName);
180 
181     /**
182      * Executes the action sequence.
183      * @param listener The listener to be notified when the sequence finishes
184      * @param async Whether the action is synchronous or asynchronous.
185      * @return <code>int</code> indicating success
186      * @see IRuntimeContext#RUNTIME_STATUS_FAILURE
187      * @see IRuntimeContext#RUNTIME_STATUS_SUCCESS
188      */
189     public int executeSequence(IActionCompleteListener listener, boolean async);
190 
191     /**
192      * The Url Factory is used for building URL's that link to this or another application
193      * @return the URL Factory
194      */
195     public IPentahoUrlFactory getUrlFactory();
196     /**
197      * @return The name of the solution holding the currently executing action sequence
198      */
199     public String   getSolutionName();
200     /**
201      * @return The path within the solution holding the currently executing action sequence
202      */
203     public String   getSolutionPath();
204     /**
205      * @return The component in the action seqeuence that's being executed
206      */
207     public String   getCurrentComponentName();
208     /**
209      * @return The session that started execution of the current action sequence
210      */
211     public IPentahoSession getSession();
212     /**
213      * Writes a message to the audit log.
214      * @param messageType Message type as defined in <tt>MessageTypes</tt>
215      * @param message Message to appear in the log
216      * @param value Value of an object to be logged.
217      * @param duration For time-tracked execution paths, indicates the duration the task took
218      * @see org.pentaho.core.audit.IAuditEntry
219      * @see IAuditable
220      * @see org.pentaho.core.audit.MessageTypes
221      */
222     public void audit(String   messageType, String   message, String   value, long duration);
223 
224     /**
225      * Returns the named input parameter. This will search amongst all the input parameter providers
226      * (<tt>IParameterProvider</tt>) in order until it finds the input parameter and returns it.
227      * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
228      * <code>null</code>
229      * @param name The name of the parameter to get
230      * @return The parameter
231      * @see org.pentaho.core.solution.IParameterProvider
232      */
233     public IActionParameter getInputParameter(String   name);
234     /**
235      * Returns the named output parameter. This will search amongst all the output parameter providers
236      * (<tt>IParameterProvider</tt>) in order until it finds the output parameter and returns it.
237      * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
238      * <code>null</code>
239      * @param name The name of the parameter to get
240      * @return The requested parameter
241      * @see org.pentaho.core.solution.IParameterProvider
242      */
243     public IActionParameter getOutputParameter(String   name);
244 
245     /**
246      * Gets the named resource definition from the executing action sequence.
247      * Throws a <tt>NullPointerException</tt> if the resource is not found. This method never returns
248      * <code>null</code>
249      * @param name The named resource to get
250      * @return The resource if it exists.
251      * @see IActionResource
252      */
253     public IActionResource getResourceDefintion(String   name);
254 
255     /**
256      * Gets the value of the specified input parameter.
257      * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
258      * <code>null</code>
259      * @param name The named parameter to retrieve
260      * @return The <tt>IActionParameter#getValue()</tt>
261      * @see IActionParameter
262      */
263     public Object   getInputParameterValue(String   name);
264 
265     /**
266      * Gets the value of the specified input parameter as a <code>String</code>.
267      * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
268      * <code>null</code>
269      * @param name The named parameter to retrieve
270      * @return The <tt>IActionParameter#getStringValue()</tt>
271      * @see IActionParameter
272      */
273     public String   getInputParameterStringValue(String   name);
274 
275     /**
276      * Gets the named resource as an <tt>InputStream</tt>. This is just a utility
277      * method that interfaces to <tt>ISolutionRepository</tt>
278      * @param actionResource The resource to get from the <code>SolutionRepository</code>
279      * @return The <code>InputStream</code> that contains the resource.
280      * @see ISolutionRepository#getResourceInputStream(IActionResource)
281      */
282     public InputStream getResourceInputStream(IActionResource actionResource);
283     /**
284      * Gets the named resource as a <tt>DataSource</tt>. This is just a utility
285      * method that interfaces to <tt>ISolutionRepository</tt>
286      * @param actionResource The resource to get from the <code>SolutionRepository</tt>
287      * @return The <code>DataSource</code>
288      * @see ISolutionRepository#getResourceDataSource(IActionResource)
289      */
290     public DataSource   getResourceDataSource(IActionResource actionResource);
291     /**
292      * Gets the named resource as a <tt>Reader</tt>. This is just a utility
293      * method that interfaces to <tt>ISolutionRepository</tt>
294      * @param actionResource The resource to get from the <code>SolutionRepository</tt>
295      * @return The <code>Reader</code>
296      * @see ISolutionRepository#getResourceReader(IActionResource)
297      */
298     public Reader getResourceReader(IActionResource actionParameter) throws IOException;
299 
300     /**
301      * Gets the named resource as a <tt>String</tt>. This is just a utility
302      * method that interfaces to <tt>ISolutionRepository</tt>
303      * @param actionResource The resource to get from the <code>SolutionRepository</tt>
304      * @return The <code>String</code>
305      * @see ISolutionRepository#getResourceAsString(IActionResource)
306      */
307     public String   getResourceAsString(IActionResource actionParameter) throws IOException;
308 
309     /**
310      * Gets the named resource as a <tt>Document</tt>. This is just a utility
311      * method that interfaces to <tt>ISolutionRepository</tt>
312      * @param actionResource The resource to get from the <code>SolutionRepository</tt>
313      * @return The <code>DataSource</code>
314      * @see ISolutionRepository#getResourceAsDocument(IActionResource)
315      */
316     public Document getResourceAsDocument(IActionResource actionParameter) throws IOException;
317     /**
318      * Sets the value of a named output parameter
319      * @param name The name of the output parameter
320      * @param output The value to set the output parameter to
321      */
322     public void setOutputValue(String   name, Object   output);
323     /**
324      * Adds a parameter to the current inputs.  A component can be use this to create parameters for internal use or for new outputs.
325      * @param name The name of the temporary parameter
326      * @param output The value to set the temporary parameter to
327      */
328     public void addTempParameter(String   name, IActionParameter output);
329     /**
330      * Returns an output stream for writing. 
331      * @param outputName The name of the output
332      * @param mimeType The mime type of the output
333      * @param extension The file extension of the output
334      * @return OutputStream for writing to
335      */
336     public OutputStream getOutputStream(String   outputName, String   mimeType, String   extension);
337     /**
338      * Returns an input stream from an input parameter, if the input parameter is
339      * a content item.
340      * @param parameterName The name of the parameter
341      * @return An InputStream from the content item
342      */
343     public InputStream getInputStream(String   parameterName);
344     
345     /**
346      * Get's the content item associated with the parameter, and returns the content item's
347      * datasource
348      * @param parameterName The name of the parameter
349      * @return The DataSource from the Content Item
350      * @see IContentItem#getDataSource()
351      */
352     public DataSource   getDataSource(String   parameterName);
353     /**
354      * @return a <tt>Set</tt> containing all the inputs in the current action.
355      */
356     public Set getInputNames();
357     /**
358      * @return a <tt>Set</tt> containing the resource names in the action
359      */
360     public Set getResourceNames();
361     /**
362      * @return a <tt>Set</tt> containing the output names in the current action
363      */
364     public Set getOutputNames();
365 
366     /**
367      * Does parameter substitution on the input string, searching for all parameter declarations in the input
368      * string, and substituting the value from the matching input parameter. In other words, it replaces 
369      * {REGION} with the value of the input parameter called REGION.
370      * @param format The string containing possible parameter references
371      * @return String with parameters resolved.
372      */
373     public String   applyInputsToFormat(String   format);
374 
375     /**
376      * Does parameter substitution on the input string, searching for all parameter declarations in the input
377      * string, and substituting the value from the matching input parameter. In other words, it replaces 
378      * {REGION} with the value of the input parameter called REGION.
379      * @param format The string containing possible parameter references
380      * @param Resolver for parameters for overriding behavior
381      * @return String with parameters resolved.
382      */
383     public String   applyInputsToFormat(String   format, IParameterResolver resolver);
384     
385     /**
386      * Adds an input parameter to the list of all inputs for the action sequence
387      * @param name The name of the parameter (the key to the parameter map)
388      * @param param The parameter to add
389      * @see IActionParameter
390      */
391     public void addInputParameter(String   name, IActionParameter param);
392 
393     /**
394      * @return true if the current output device allows 
395      * user feedback (i.e. parameter input forms)
396      */
397     public boolean feedbackAllowed();
398     
399     /**
400      * Interfaces to the current output handler to get the content item
401      * that is handling feedback (i.e. parameter input forms)
402      * @return the Content Item for user input
403      * @see IContentItem
404      * @see IOutputHandler
405      */
406     public IContentItem getFeedbackContentItem();
407     
408     /**
409      * Interfaces to the current output handler to get the content item
410      * that describes the output from this request's component execution.
411      * @return The content item for output
412      * @see IContentItem
413      * @see IOutputHandler
414      */
415     public IContentItem getOutputContentItem();
416 
417     /**
418      * Interfaces to the current output handler to get the named content item
419      * from this request's component execution.
420      * @param outputName the name of the output
421      * @return The requested content item
422      * @see IContentItem
423      * @see IOutputHandler
424      */
425     public IContentItem getOutputContentItem(String   outputName);
426 
427     /**
428      * Returns a url to the passed in content item that can be used to retrieve
429      * the content.
430      * 
431      * @param parameterName
432      *            the parameter name of the content
433      * @return a string representing the URL or null if the name is not a
434      *         content item or is not a valid name.
435      */
436     public String   getContentUrl(IContentItem contentItem);
437 
438     /**
439      * Generates a parameter acquisition form for required
440      * parameters. This writes directly to the output stream
441      * provided by the output handler.
442      * @throws IOException
443      * @see IOutputHandler
444      */
445     public void sendFeedbackForm() throws IOException;
446 
447     /**
448      * @deprecated
449      * 
450      * Adds a feedback parameter for prompts based on an Action Parameter. Uses
451      * the Selections defined in the Action Parameter for the options and sets
452      * the default to the current value
453      * 
454      * @param actionParam
455      *            The Action Parameter to use as the model for the prompt
456      */
457     public void createFeedbackParameter(IActionParameter actionParam);
458 
459     /**
460      * Adds a feedback parameter (essentially a form input field) for a
461      * required input. 
462      * @param selMap Maps <code>IPentahoResultSet</code> objects to selection objects
463      * @param fieldName Name of the form field
464      * @param defaultValues default values for the input field
465      * @see SelectionMapper
466      */
467     public void createFeedbackParameter(SelectionMapper selMap, String   fieldName, Object   defaultValues);
468 
469     /**
470      * Adds a scalar feedback parameter
471      * @param fieldName Name of the input field
472      * @param displayName display name of the input field
473      * @param hint Fly-over hint for the input field
474      * @param defaultValue Default value for the input field
475      * @param visible Whether the input field is visible or not
476      * @see XForm
477      */
478     public void createFeedbackParameter(String   fieldName, String   displayName, String   hint, String   defaultValue, boolean visible);
479     /**
480      * Creates a feedback parameter that uses a list for the values
481      * @param fieldName The name of the field
482      * @param displayName Display name
483      * @param hint Fly-over hint for the input field
484      * @param defaultValues Default value of the input field
485      * @param values List of values 
486      * @param dispNames Map of display names
487      * @param displayStyle how to display the control
488      * @see XForm
489      */
490     public void createFeedbackParameter(String   fieldName, String   displayName, String   hint, Object   defaultValues, List values, Map dispNames, String   displayStyle);
491 
492     /**
493      * @return the current status of execution
494      */
495     public int getStatus();
496 
497     /**
498      * @return List of messages saved up during execution. This is used to provide
499      * failure feedback to the user.
500      */
501     public List getMessages();
502 
503     /**
504      * Creates a new runtime context that is a child of this instance
505      * 
506      * @param persisted
507      *            Should the runtime data be persisted
508      * @return Instance id of the new RuntimeContext
509      */
510     public String   createNewInstance(boolean persisted);
511 
512     /**
513      * Creates a new runtime context that is a child of this instance and sets
514      * attributes of the runtime data from the parameter Map
515      * 
516      * @param persisted
517      *            Should the runtime data be persisted
518      * @param parameters
519      *            parameters for the new instance
520      * @return Instance id of the new RuntimeContext
521      */
522     public String   createNewInstance(boolean persisted, Map parameters);
523 
524     /**
525      * Creates a new runtime context that is a child of this instance and sets
526      * attributes of the runtime data from the parameter Map, and can
527      * optionally cause the new instance to be forcibly written to the
528      * underlying persistence mechanism.
529      * 
530      * @param persisted
531      *            Should the runtime data be persisted
532      * @param parameters
533      *            parameters for the new instance
534      * @param forceImmediateWrite
535      *            if true, will call the new runtime element's forceSave method
536      *            before returning.
537      * @return Instance id of the new RuntimeContext
538      */
539     public String   createNewInstance(boolean persisted, Map parameters, boolean forceImmediateWrite);
540 
541     public void dispose();
542 
543     /**
544      * Sets the xsl file to be used to generate the parameter page for the
545      * current component. The parameter should be a full path from the solution
546      * root starting with a /, or it should be a path relative to the directory
547      * of the current action sequence.
548      * 
549      * @param xsl
550      *            The name of the XSL file
551      */
552     public void setParameterXsl(String   xsl);
553 
554     /**
555      * Sets the target window that the content will be displayed in. This name
556      * is used at the target in an Window.open() javascript call made when the
557      * submit button on the parameter page is clicked.
558      * 
559      * @param target
560      *            Window name
561      */
562     public void setParameterTarget(String   target);
563 
564     /**
565      * Forces the immediate write of runtime data to underlying persistence
566      * mechanism. In the case of using Hibernate for the runtime data
567      * persistence, this works out to a call to HibernateUtil.flush().
568      */
569     public void forceSaveRuntimeData();
570 
571     /**
572      * Gets the output type prefered by the handler. Values are defined in
573      * org.pentaho.core.solution.IOutputHander and are OUTPUT_TYPE_PARAMETERS,
574      * OUTPUT_TYPE_CONTENT, or OUTPUT_TYPE_DEFAULT
575      * 
576      * @return Output type
577      */
578     public int getOutputPreference();
579 
580     /**
581      * Sets the output handler for the runtime context
582      * 
583      * @param outputHandler
584      *            The output handler
585      * 
586      */
587     public void setOutputHandler(IOutputHandler outputHandler);
588     
589     /**
590      * Sets the default prompt status PROMPT_NO, PROMPT_WAITING, PROMPT_NOW
591      * @param status
592      */
593     public void setPromptStatus( int status );
594 }
595
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags