Source code

001/*
002 * Copyright (c) 2009-2010 The Regents of the University of California.
003 * All rights reserved.
004 *
005 * '$Author: crawl $'
006 * '$Date: 2017-08-23 20:27:50 +0000 (Wed, 23 Aug 2017) $' 
007 * '$Revision: 34619 $'
008 * 
009 * Permission is hereby granted, without written agreement and without
010 * license or royalty fees, to use, copy, modify, and distribute this
011 * software and its documentation for any purpose, provided that the above
012 * copyright notice and the following two paragraphs appear in all copies
013 * of this software.
014 *
015 * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
016 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
017 * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
018 * THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
019 * SUCH DAMAGE.
020 *
021 * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
022 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
023 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
024 * PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
025 * CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
026 * ENHANCEMENTS, OR MODIFICATIONS.
027 *
028 */
029
030package org.kepler.provenance;
031
032import java.io.Closeable;
033import java.util.Date;
034import java.util.List;
035import java.util.Map;
036
037import org.kepler.objectmanager.lsid.KeplerLSID;
038import org.kepler.sms.NamedOntClass;
039import org.kepler.util.WorkflowRun;
040
041import ptolemy.data.Token;
042import ptolemy.kernel.util.NamedObj;
043
044/**
045 * An interface for querying provenance stores.
046 *
047 * @author Ilkay Altintas, Derik Barseghian, Daniel Crawl
048 * @version $Id: Queryable.java 34619 2017-08-23 20:27:50Z crawl $
049 *
050 */
051
052public interface Queryable extends Closeable
053{
054    /** Disconnect from provenance store. */
055    public void disconnect() throws QueryException;
056
057    /** Get a list of workflow names. */
058    public List<String> getWorkflows() throws QueryException;
059
060    /** Get a workflow name. 
061     *  @param lsid the workflow's LSID.
062     *  @return the workflow name if found, otherwise null.
063     */
064    public String getWorkflowName(KeplerLSID lsid) throws QueryException;
065    
066    /** Get a workflow name for an execution LSID.
067     *  @param lsid the execution LSID.
068     *  @return the workflow name if found, otherwise null.
069     */
070    public String getWorkflowNameForExecution(KeplerLSID lsid) throws QueryException;
071    
072    /** Get a list of all executions. */
073    public List<Integer> getExecutions() throws QueryException;
074
075    /** Get a list of all execution LSIDs. */
076    public List<KeplerLSID> getExecutionLSIDs() throws QueryException;
077    
078    /** Get a list of executions for a specific workflow. */
079    public List<Integer> getExecutionsForWorkflow(String workflow) 
080        throws QueryException;
081
082    /** Get the execution for a specific run LSID. If no execution
083     *  exists, returns null.
084     */
085    public Integer getExecutionForExecutionLSID(KeplerLSID runLSID)
086        throws QueryException;
087    
088    /** Get the execution LSID for a specific execution id. If no execution
089     *  exists, returns null.
090     */
091    public KeplerLSID getExecutionLSIDForExecution(Integer execId)
092        throws QueryException;
093    
094    /** Get a list of executions for a specific execution annotation. */
095    public List<Integer> getExecutionsForAnnotation(String annotation) 
096        throws QueryException;
097
098    /** Get the start and end timestamps of an execution.
099     *  @param execId the execution id
100     *  @return a two-element array: the first entry is the start timestamp,
101     *  and the second is the end timestamp. If the execution id is not found,
102     *  returns null.
103     */
104    public Date[] getTimestampsForExecution(int execId)
105        throws QueryException;
106    
107    /** Get workflow MoML for an execution. */
108    public String getMoMLForExecution(int execId) throws QueryException;
109    
110    /** Get workflow MoML for an execution LSID */
111    public String getMoMLForExecution(KeplerLSID lsid) throws QueryException;
112    
113    /** Get workflow MoMLs for a list of execution lsids. Only returns one copy 
114     *  of any duplicates.
115     */
116    public List<String> getMoMLForExecutionLSIDs(List<KeplerLSID> lsids)
117        throws QueryException;
118    
119    /** Get the workflow object for a execution id. */
120    public NamedObj getWorkflowForExecution(Integer execId) 
121        throws QueryException;
122    
123    /** Get executions within a timespan. */
124    public List<Integer> getExecutionsForTimespan(Date start,
125        Date end) throws QueryException;
126    
127    /** Get executions that have %workflowName% and %userName%. */
128    public List<Integer> getExecutionsForWorkflowRuns(String workflowName,
129        String userName) throws QueryException;
130    
131    //TODO better name?
132    /** Get executions that have %workflowName% and %userName%. and 
133     *  startTime > after. 
134     */
135    public List<Integer> getExecutionsForWorkflowRunsAfter(String workflowName,
136        String userName, Date after) throws QueryException;
137    
138    /** Get executions that have %workflowName% and %userName%. and 
139     * startTime >= after and startTime <= before.
140     */
141    public List<Integer> getExecutionsForWorkflowRuns(String workflowName,
142        String userName, Date after, Date before, int execIdAfter,
143        int execIdBefore) throws QueryException;
144
145    public List<KeplerLSID> getExecutionLSIDsForWorkflowRuns(String workflowName,
146            String userName, Date after, Date before, int execIdAfter,
147            int execIdBefore) throws QueryException;
148    
149    //TODO better name?
150    /** Get exections that have %workflowName% and %userName%, and 
151     *  startTime < before.
152     */
153    public List<Integer> getExecutionsForWorkflowRunsBefore(
154        String workflowName, String userName, Date before)
155        throws QueryException;
156
157    /** Get the last execution for a workflow. NOTE: the LSID revision 
158     *  is ignored.
159     *  @param lsid the workflow lsid.
160     *  @return if workflow has been executed, the last execution id.
161     *  otherwise, returns null.
162     */
163    public Integer getLastExecutionForWorkflow(KeplerLSID lsid)
164        throws QueryException;
165
166    /** Get the last execution for a workflow.
167     *  @param workflow the workflow name
168     *  @return if workflow has been executed, the last execution id.
169     *  otherwise, returns null.
170     */
171    public Integer getLastExecutionForWorkflow(String workflow)
172        throws QueryException;
173
174    /** Get the last execution LSID for a workflow.
175     *  @param workflow the workflow name.
176     *  @return execution lsid
177     */
178    public KeplerLSID getLastExecutionLSIDForWorkflow(String workflow)
179        throws QueryException;
180    
181    /** Get the last execution LSID for a workflow.
182     *  @param lsid the workflow LSID.
183     *  @return execution lsid
184     */
185    public KeplerLSID getLastExecutionLSIDForWorkflow(KeplerLSID lsid)
186        throws QueryException;
187
188    /** Get the error for an execution. Returns null if no error message
189     *  was found. NOTE: returning null is not an indication if the
190     *  execution had an error.
191     *  @see isErrorForExecution
192     *  @param lsid the workflow execution lsid. 
193     */
194    public String getErrorForExecution(KeplerLSID lsid) throws QueryException;
195
196    /** Returns true if the execution had an error. */
197    public boolean isErrorForExecution(KeplerLSID executionLSID) throws QueryException;
198
199    /** Get an sequence of tokens for an execution.
200     *  @param execId the execution id
201     *  @param last if true, the sequence starts at the last token created
202     *  and goes backwards to the first; otherwise the sequence starts at
203     *  the first token.
204     */
205    public List<Integer> getTokensForExecution(int execId, boolean last)
206        throws QueryException;
207    
208    /** Get an sequence of tokens for an execution.
209     *  @param execId the execution id
210     *  @param portId the port id. If null, returns the ids of
211     *  tokens read in entire execution.
212     *  @param last if true, the sequence starts at the last token created
213     *  and goes backwards to the first; otherwise the sequence starts at
214     *  the first.
215     */
216    public List<Integer> getTokensForExecution(int execId, Integer portId,
217        boolean last) throws QueryException;
218
219    /** Get the firing id(s) of the actor(s) that read or wrote a token.
220     *  @param tokenId the token id
221     *  @param read If true, return the actor(s) firing id(s) that read
222     *  the token. Otherwise, return the actor firing that wrote the token.
223     */
224    public List<Integer> getActorFiringForToken(int tokenId, boolean read)
225        throws QueryException;
226  
227    /** Get tokens for a firing.
228     *  @param fireId the firing id
229     *  @param read if true, get the tokens read; otherwise get the tokens
230     *  written.
231     */
232    public List<Integer> getTokensForFiring(int fireId, boolean read)
233        throws QueryException;
234    
235    /** Get the Token. */
236    public Token getToken(int tokenId) throws QueryException;
237    
238    /** Get the value of a token. */
239    public String getTokenValue(int tokenId) throws QueryException;
240
241    /** Get the type of a token. */
242    public String getTokenType(int tokenId) throws QueryException;
243
244    /** Get the channel that a token was read or written on.
245     *  @param tokenId the token id
246     *  @param read if true, return the channel the token was read on.
247     *  otherwise, return the channel the token was written on.
248     *  @param fireId the actor firing id. can be null for writes, but
249     *  must be specified for reads.
250     *  @return the channel the token was read or written on.
251     */
252    public Integer getChannelForToken(int tokenId, boolean read, Integer fireId) throws QueryException;
253    
254    /** Get an actor's name for a firing id. */
255    public String getActorName(int fireId) throws QueryException;
256
257    /** Get an actor's type for a firing id. */
258    public String getActorType(int fireId) throws QueryException;
259   
260    /** Get the id of entity. If entity is not found, returns null.
261     *  @param entityName name of entity.
262     *  @param lsid the workflow LSID. NOTE: the revision is ignored.
263     */
264    public Integer getEntityId(String entityName, KeplerLSID lsid)
265        throws QueryException;
266
267    /** Get the id of entity. If workflow or entity is not found, returns null. 
268     *  @param entityName the name of the entity. 
269     *  @param workflowName the name of the workflow.
270     */
271    public Integer getEntityId(String entityName, String workflowName)
272        throws QueryException;
273    
274    /** Get the type of entity. */
275    public String getEntityType(Integer entityId) throws QueryException;
276    
277    /** Get the workflow id of entity. */
278    public Integer getEntityWorkflowId(Integer entityId) throws QueryException;
279    
280    /** Get an actor's parameter name value pairs for a firing id.
281     *  NOTE: Parameter values may change during a firing; this method
282     *  returns the values at the <b>start</b> of the firing. 
283     */
284    public Map<String,String> getParameterNameValuesForFiring(int fireId)
285        throws QueryException;
286   
287    /** Get the parameter name value pairs for an execution. NOTE: Parameter
288     *  values may change during an execution; this method returns the
289     *  values at the <b>start</b> of the execution.
290     */
291    public Map<String,String> getParameterNameValuesForExecution(int execId)
292        throws QueryException;
293  
294    /** Get the latest value of a parameter. 
295     *  @param parameter the parameter name.
296     *  @param lsid the workflow lsid
297     *  @return the latest value of the parameter. If the workflow LSID or
298     *  parameter name cannot be found, returns null.
299     */
300    public String getParameterValueLatest(String parameter, KeplerLSID lsid)
301        throws QueryException;
302
303    /** Get the value of a parameter at a specific time. 
304     * @param timestamp the time
305     * @param parameter the parameter name
306     * @param lsid the workflow lsid
307     * @return the value of the parameter at the specified time. If the
308     * workflow LSID or parameter name cannot be found, returns null.
309     */
310    public String getParameterValueAtTime(Date timestamp, String parameter,
311        KeplerLSID lsid) throws QueryException;
312
313    /** Get the token(s) that generated a token. */
314    public List<Integer> getImmediateDependencies(int tokenId)
315        throws QueryException;
316
317    /** Get a file associated with an execution. */
318    public List<byte[]> getAssociatedDataForExecution(int execId,
319        Map<String,String> metadataMap, boolean matchAny)
320        throws QueryException;
321    
322    /** Get any associated keys-values for an execution. */
323    public Map<String,String> getAssociatedKeysValuesForExecution(int execId)
324        throws QueryException;
325    
326    /** Get "workflow runs" for a list of execution LSIDs. A 'workflow run'
327     *  is a group of useful information related to an execution.
328     */
329    public Map<KeplerLSID, WorkflowRun> getWorkflowRunsForExecutionLSIDs(
330        List<KeplerLSID> executions) throws QueryException;
331
332    /** Get workflow runs for a user. */
333    public List<WorkflowRun> getWorkflowRunsForUser(String user) throws QueryException;
334    
335    /** Get execution ids for %tagsSearchString% (case insensitive) */
336    public List<Integer> getExecutionIdsForTags(String tagsSearchString)
337        throws QueryException;
338    
339    /** Get tags for an execution LSID */
340    public List<String> getTagsForExecutionId(int execId) 
341        throws QueryException;
342
343    /** Get the type of a tag, null if none */
344    public String getTypeForTag(String conceptId);
345
346    /** Get a map of tags and their types (context, or tagee, currently "run"
347     *  or "workflow") for an executionLSID
348     */
349    public Map<NamedOntClass, String> getTagClassesForExecutionId(
350        int execId) throws QueryException;
351
352    /** Get execution id for an execution LSID without revision. */
353    public Integer getExecutionForExecutionLSIDWithoutRevision(
354        String execLSIDWithoutRevision) throws QueryException;
355
356    /** Get execution id for execution that has the given LSID as its
357     *  oldest referral. 
358     */
359    public Integer getExecutionForOldestReferralExecutionLSIDWithoutRevision(
360        String stringWithoutRevision) throws QueryException;
361    
362    /** Get a list of executions corresponding to a specific type. */
363    public List<KeplerLSID> getExecutionsForType(WorkflowRun.type type) throws QueryException;
364    
365    /** See if an execution appears to be imported. */
366    public boolean isImportedExecution(KeplerLSID executionLSID) throws QueryException;
367
368    /** Get the ports for an actor.
369     *  @param workflow the LSID of the workflow
370     *  @param actor the fully-qualified name of the actor
371     *  @return a list of fully-qualified names of ports of the actor
372     */
373    public List<String> getPortsForActor(KeplerLSID workflow, String actor)
374        throws QueryException;
375
376    /** Get the user for a specific execution LSID. */
377    public String getUserForExecution(KeplerLSID execLSID)
378        throws QueryException;   
379
380    /** Get the user for a specific execution id. */
381    public String getUserForExecution(Integer execId)
382        throws QueryException;   
383    
384    /** Get the host id for a specific execution id. */
385    public String getHostIdForExecution(Integer execId)
386        throws QueryException; 
387    
388    /** Get the output role (port name) of a token. */
389    public String getOutputRoleToken(int tokenId) throws QueryException;
390    
391    /** Get the input role (port name) of a token. */
392    public String getInputRoleForTokenAndFireId(int tokenId, int fireId)
393        throws QueryException;   
394    
395    /** Get the parameter name value pairs for an execution, whose parameter type is
396     * either '.Parameter' or '.StringParameter' 
397     */
398    public Map<String,String> getParameterNameValuesOfSpecificTypeForExecution(int execId)
399        throws QueryException;
400    
401    /** Get the start and end timestamps of an actor firing. */
402    public Date[] getTimestampsForActorFiring(int fireId)
403        throws QueryException;  
404    
405    /** Get actor fire ids based on its full name and workflow exec ID. */
406    public List<Integer> getActorFiringIds(String actorName, Integer wfExecId) 
407        throws QueryException;
408    
409    /** Get an actor's parameter and port parameter name value pairs for a firing id.
410     *  NOTE: Parameter values may change during a firing; this method
411     *  returns the values at the <b>start</b> of the firing. 
412     */
413    public Map<String,String> getParameterAndPortParameterNameValuesForFiring(int fireId)
414        throws QueryException;
415       
416    /** Get all actor fire ids for a workflow exec ID. */
417    public List<Integer> getActorFirings(int wfExecId)
418        throws QueryException;
419        
420    /** Get the timestamp(s) when a token was read. If a token was
421     *  never read, this can return null or an empty array.
422     */
423    public Date[] getTimestampsForTokenRead(Integer tokenId)
424        throws QueryException;
425
426    /** Get the timestamp when a token was written. */
427    public Date getTimestampForTokenWrite(Integer tokenId)
428        throws QueryException;
429
430    /** Get the total execution time for an actor.
431     *
432     *  @param workflow the workflow LSID. If null, must specify execution id.
433     *  @param execLSID the execution id. If null, use the last execution of the workflow.
434     *  @param actor the full actor name.
435     *  @return the total time execution time of the actor, in milliseconds.
436     */
437    public long getTotalExecutionTimeForActor(KeplerLSID workflow, KeplerLSID execLSID,
438        String actor) throws QueryException;
439    
440    /** Get the execution times for an actor.
441     *
442     * @param workflow the workflow LSID. If null, must specify execution id.
443     * @param execLSID the execution LSID. If null, the last execution of the workflow
444     * is used.
445     * @param actor the full actor name.
446     * @return a map of actor fire id to execution time pairs. if a firing does not
447     * have a valid start or stop time, the firing is not included in the result.
448     */
449    public Map<String,Long> getExecutionTimesForActor(KeplerLSID workflow,
450        KeplerLSID execLSID, String actor) throws QueryException;
451
452    /** Get the total number of bytes read or or written by an actor over all its ports.
453     *  @param workflow the workflow LSID. If null, specify the execution id.
454     *  @param execId the execution id. If null, the last execution of the workflow
455     *  is used.
456     *  @param actor the full actor name.
457     *  @param read If true, get the bytes read. Otherwise, get the bytes written.
458     */
459    public Integer getTotalIOBytesForActor(KeplerLSID workflow, Integer execId,
460            String actor, boolean read) throws QueryException;
461
462    /** Get the number of bytes read or written by a port.
463     *
464     *  @param workflow the workflow LSID. If null, must specify execution id.
465     *  @param execId the execution id. If null, the last execution of the workflow
466     *  is used.
467     *  @param port the full port name.
468     *  @param read If true, get the bytes read. Otherwise, get the bytes written.
469     *  @return a map of port event id to bytes read/written.
470     */
471    public Map<Integer,Integer> getIOBytesForPort(KeplerLSID workflow, Integer execId,
472        String port, boolean read) throws QueryException;
473    
474    /*
475    public List<LinkIO> getLinksIO(KeplerLSID workflow, Integer execId)
476        throws QueryException;
477    */
478}