KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > pentaho > core > runtime > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getSolutionName();
200     /**
201      * @return The path within the solution holding the currently executing action sequence
202      */

203     public String JavaDoc getSolutionPath();
204     /**
205      * @return The component in the action seqeuence that's being executed
206      */

207     public String JavaDoc 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 JavaDoc messageType, String JavaDoc message, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getInputParameterValue(String JavaDoc 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 JavaDoc getInputParameterStringValue(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc name, Object JavaDoc 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 JavaDoc 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 JavaDoc outputName, String JavaDoc mimeType, String JavaDoc 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 JavaDoc 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 JavaDoc getDataSource(String JavaDoc 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 JavaDoc applyInputsToFormat(String JavaDoc 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 JavaDoc applyInputsToFormat(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc fieldName, Object JavaDoc 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 JavaDoc fieldName, String JavaDoc displayName, String JavaDoc hint, String JavaDoc 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 JavaDoc fieldName, String JavaDoc displayName, String JavaDoc hint, Object JavaDoc defaultValues, List values, Map dispNames, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags