OmeroBlitz API
Home Previous Up Next Index

omero::api::IScript

Overview

[ "ami", "amd" ] interface IScript extends ServiceInterface

Utility service for managing and launching scripts for execution by the Processor API. Typical usage might include (PYTHON):

{@code
sf = client.createSession()
svc = sf.getScriptService()
scripts = svc.getScripts()

if len(scripts) >= 1:
script_id = svc.keys()[-1]
else:
script_id = svc.uploadScript('/test/my_script.py', SCRIPT_TEXT)

params = svc.getParams(script_id)

# You will need to parse the params to create the proper input
inputs = {}

# The last parameter is how long to wait as an RInt
proc = svc.runScript(script_id, inputs, None)
try:
cb = omero.scripts.ProcessCallbackI(client, proc)
while not cb.block(1000): # ms.
pass
cb.close()
rv = proc.getResults(0)
finally:
proc.close(False)
}
See OMERO.scripts for more information.

Operation Index

getScripts
This method returns official server scripts as a list of model::OriginalFile objects.
getScriptsByMimetype
This method returns official server scripts identified with the specified extension as a list of model::OriginalFile objects.
getUserScripts
Returns non-official scripts which have been uploaded by individual users.
getScriptID
Get the id of an official script by the script path.
getScriptText
Get the text from the server for the script with given id.
uploadScript
Upload a user script to the server and return the id.
uploadOfficialScript
Like {@code uploadScript} but is only callable by administrators.
editScript
Modify the text for the given script object.
getScriptWithDetails
Get the script from the server with details from OriginalFile @param scriptID see above @return see above @throws ApiUsageException
getParams
Get the parameters that the script takes and returns, along with other metadata available from the script.
deleteScript
Delete the script on the server with id.
runScript
If ResourceError is thrown, then no {@code Processor} is available.
canRunScript
Returns true if there is a processor which will run the given script.
validateScript
Used internally by processor.py to check if the script attached to the model::Job has a valid script attached, based on the {@code acceptsList} and the current security context.

Operations

OriginalFileList getScripts() throws ServerError

This method returns official server scripts as a list of model::OriginalFile objects. These scripts will be executed by the server if submitted via {@code runScript}. The input parameters necessary for proper functioning can be retrieved via {@code getParams}. The model::OriginalFile::path value can be used in other official scripts via the language specific import command, since the script directory will be placed on the appropriate environment path variable.

{@code
scripts = scriptService.getScripts()
for script in scripts:
text = scriptService.getScriptText(script.id.val)
# First character is a "/" symbol
path = script.path.val[1:\]
path = path.replace("/",".")
print "Possible import: %s" % path
}

Return Value

see above.

Exceptions

OriginalFileList getScriptsByMimetype(string mimetype) throws ServerError

This method returns official server scripts identified with the specified extension as a list of model::OriginalFile objects. These scripts will be executed by the server if submitted via {@code runScript}. The input parameters necessary for proper functioning can be retrieved via {@code getParams}. The model::OriginalFile::path value can be used in other official scripts via the language specific import command, since the script directory will be placed on the appropriate environment path variable.

{@code
scripts = scriptService.getScripts("py")
for script in scripts:
text = scriptService.getScriptText(script.id.val)
path = script.path.val[1:\] # First symbol is a "/"
path = path.replace("/",".")
print "Possible import: %s" % path
}

Parameters

mimetype
the mimetype identifying the scripts.

Return Value

see above.

Exceptions

OriginalFileList getUserScripts(IObjectList acceptsList) throws ServerError

Returns non-official scripts which have been uploaded by individual users. These scripts will not be run by the server, though a user can start a personal usermode processor which will allow the scripts to be executed. This is particularly useful for testing new scripts.

long getScriptID(string path) throws ServerError

Get the id of an official script by the script path. The script service ensures that all script paths are unique. Note: there is no similar method for user scripts (e.g. {@code getUserScriptID}) since the path is not guaranteed to be unique.

Parameters

path
The name of the script.

Return Value

see above.

Exceptions

string getScriptText(long scriptID) throws ServerError

Get the text from the server for the script with given id.

Parameters

scriptID
see above.

Return Value

see above.

Exceptions

long uploadScript(string path, string scriptText) throws ServerError

Upload a user script to the server and return the id. This method checks that a script with that names does not exist and that the script has parameters if possible, i.e. a usermode processor is running which for the current user.

Parameters

path
see above.
scriptText
see above.

Return Value

The new id of the script.

Exceptions

long uploadOfficialScript(string path, string scriptText) throws ServerError

Like {@code uploadScript} but is only callable by administrators. The parameters for the script are also checked.

void editScript(model::OriginalFile fileObject, string scriptText) throws ServerError

Modify the text for the given script object.

Parameters

fileObject
see above.
scriptText
see above.

Exceptions

RTypeDict getScriptWithDetails(long scriptID) throws ServerError

Get the script from the server with details from OriginalFile

Parameters

scriptID
see above

Return Value

see above

Exceptions

grid::JobParams getParams(long scriptID) throws ServerError

Get the parameters that the script takes and returns, along with other metadata available from the script.

Parameters

scriptID
see above.

Return Value

see above.

Exceptions

void deleteScript(long scriptID) throws ServerError

Delete the script on the server with id. The file will also be removed from disk.

Parameters

scriptID
Id of the script to delete.

Exceptions

grid::ScriptProcess* runScript(long scriptID, RTypeDict inputs, RInt waitSecs) throws ServerError

If ResourceError is thrown, then no {@code Processor} is available. Use {@code scheduleJob} to create a model::ScriptJob in the Waiting state. A {@code Processor} may become available.

{@code
try:
proc = scriptService.runScript(1, {}, None)
except ResourceError:
job = scriptService.scheduleScript(1, {}, None)
}
The {@code ScriptProcess} proxy MUST be closed before exiting. If you would like the script execution to continue in the background, pass True as the argument.
{@code
try:
proc.poll()         # See if process is finished
finally:
proc.close(True)    # Detach and execution can continue
# proc.close(False) # OR script is immediately stopped.
}

bool canRunScript(long scriptID) throws ServerError

Returns true if there is a processor which will run the given script.

Either the script is an official script and this method will return true (though an individual invocation may fail with an ResourceError for some reason) or this is a user script, and a usermode processor must be active which takes the scripts user or group.

model::OriginalFile validateScript(model::Job j, IObjectList acceptsList) throws ServerError

Used internally by processor.py to check if the script attached to the model::Job has a valid script attached, based on the {@code acceptsList} and the current security context. An example of an acceptsList might be

Experimenter(myUserId, False)
, meaning that only scripts belonging to me should be trusted. An empty list implies that the server should return what it would by default trust. A valid script will be returned if it exists; otherwise null.


Home Previous Up Next Index