## org.autoplot.jythonsupport.Util

Utilities for Jython scripts in both the datasource and application contexts.

## Util( )

## fileCanRead

fileCanRead( String file ) → boolean

return true if the file can be read. This is introduced to avoid imports of java.io.File.

### Parameters

file - the file or directory.

### Returns:

true if the file can be read.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## fileExists

fileExists( String file ) → boolean

return true if the file exists. This is introduced to avoid imports of java.io.File.

### Parameters

file - file or local file Autoplot URI

### Returns:

true if the file exists.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## generateTimeRanges

generateTimeRanges( String spec, String srange ) → String[]

Given a spec to format timeranges and a range to contain each timerange, produce a list of all timeranges covering the range formatted with the spec. For example, `generateTimeRanges( "%Y-%m-%d", "Jun 2009" )` would result in 2009-06-01, 2009-06-02, ..., 2009-06-30. This is limited to create no more than 100000 elements.

### Parameters

spec - such as "%Y-%m". Note specs like "%Y%m" will not be parsable.
srange - range limiting the list, such as "2009"

### Returns:

a string array of formatted time ranges, such as [ "2009-01", "2009-02", ..., "2009-12" ]

### See Also:

DatumRangeUtil#parseTimeRangeValid(java.lang.String) to convert to DatumRange objects.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getAllCompletions

getAllCompletions( String file ) → String[]

return a list of all completions, even if they are not complete. This is useful in the IDL context as well as Jython scripts. This will perform the completion for where the carot is at the end of the string. All completions are returned, so for example http://autoplot.org/data/somedata.cdf?noDep is returned as well as http://autoplot.org/data/somedata.cdf?Magnitude.

### Parameters

file - for example http://autoplot.org/data/somedata.cdf?

### Returns:

list of completions, containing the entire URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getAutoplotScriptingVersion

getAutoplotScriptingVersion( ) → String

this returns a double indicating the current scripting version, found at the top of autoplot2023.py in AUTOPLOT_DATA/jython/autoplot2023.py. Do not parse this number and expect it to work in future versions!

### Returns:

the version, such as v1.50.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getCompletions

getCompletions( String file ) → String[]

return a list of completions. This is useful in the IDL context as well as Jython scripts. This will perform the completion for where the carot is at the end of the string. Only completions where maybePlot indicates the URI is now valid are returned, so for example http://autoplot.org/data/somedata.cdf?noDep is not returned and http://autoplot.org/data/somedata.cdf?Magnitude is.

### Parameters

file - for example http://autoplot.org/data/somedata.cdf?

### Returns:

list of completions, containing the entire URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSet

getDataSet( String suri, String stimeRange, ProgressMonitor mon ) → QDataSet

load the data specified by URI into Autoplot's internal data model. This will block until the load is complete, and a ProgressMonitor object can be used to monitor the load. This adds a timeRange parameter so that TimeSeriesBrowse-capable datasources can be used from AutoplotServer.

### Parameters

suri - the URI of the dataset, such as "http://autoplot.org/data/2010_061_17_41_40.txt?column=field8"
stimeRange - a string representing the timerange to load, such as 2012-02-02/2012-02-03
mon - progress monitor object.

### Returns:

QDataSet from the load.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSet

getDataSet( String suri, DatumRange timeRange, ProgressMonitor monitor ) → QDataSet

load the data specified by URI into Autoplot's internal data model. This will block until the load is complete, and a ProgressMonitor object can be used to monitor the load. This adds a timeRange parameter so that TimeSeriesBrowse-capable datasources can be used from AutoplotServer.

### Parameters

suri - the URI of the dataset, such as "http://autoplot.org/data/2010_061_17_41_40.txt?column=field8"
timeRange - null or the timerange to load, if the data supports time series browsing.
monitor - progress monitor object, or null (None in Jython).

### Returns:

null or the dataset for the URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSet

getDataSet( String suri, ProgressMonitor mon ) → QDataSet

load the data specified by URL into Autoplot's internal data model. This will block until the load is complete, and a ProgressMonitor object can be used to monitor the load.

### Parameters

suri - the URI of the dataset, such as "http://autoplot.org/data/2010_061_17_41_40.txt?column=field8"
mon - a progress monitor to monitor the load, or null (None in Jython)

### Returns:

the dataset, or null.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSet

getDataSet( String suri ) → QDataSet

load the data specified by URI into Autoplot's internal data model. This will block until the load is complete.

### Parameters

suri - the URI of the dataset, such as "http://autoplot.org/data/2010_061_17_41_40.txt?column=field8"

### Returns:

null or dataset for the URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSet

getDataSet( String suri, String stimerange ) → QDataSet

load the data specified by URI into Autoplot's internal data model. This will block until the load is complete.

### Parameters

suri - the URI of the dataset, such as "http://autoplot.org/data/2010_061_17_41_40.txt?column=field8"
stimerange - timerange like "2012-02-02/2012-02-03"

### Returns:

null or data set for the URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSet

getDataSet( String suri, DatumRange timerange ) → QDataSet

load the data specified by URI into Autoplot's internal data model. This will block until the load is complete.

### Parameters

suri - the URI of the dataset, such as "http://autoplot.org/data/2010_061_17_41_40.txt?column=field8"
timerange - timerange object

### Returns:

null or data set for the URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSetFromStream

getDataSetFromStream( String spec, java.io.InputStream in, ProgressMonitor mon ) → QDataSet

load data from the input stream into Autoplot internal data model. This will block until the load is complete. This works by creating a temporary file and then using the correct reader to read the data. When the data source is able to read directly from a stream, no temporary file is created. Currently this always loads to a file, and therefore does not support applets. This may have been introduced to support scripts, but it's not clear who uses it.

### Parameters

spec - the extension and any parsing parameters, such as "vap+bin:?recLength=2000&rank2=1:"
in - the input stream
mon - a progress monitor.

### Returns:

QDataSet the dataset or null.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSets

getDataSets( java.util.List uris, ProgressMonitor mon ) → java.util.List

load multiple uris simultaneously. This will read all the data at once, returning all data or throwing one of the exceptions.

### Parameters

uris - a list of URI strings.
mon - monitor for the aggregate load. TODO: Each uri should given equal shares of the task.

### Returns:

list of loaded data
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSets

getDataSets( java.util.List uris, DatumRange timerange, ProgressMonitor mon ) → java.util.List

load multiple uris simultaneously. This will read all the data at once, returning all data or throwing one of the exceptions.

### Parameters

uris - a list of URI strings.
timerange - the timerange to load, and the reader may return data from a longer interval.
mon - monitor for the aggregate load. TODO: Each uri should given equal shares of the task.

### Returns:

list of loaded data
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDataSource

getDataSource( String suri ) → org.autoplot.datasource.DataSource

returns the dataSource for the given URI. This will include capabilities, like TimeSeriesBrowse.

### Parameters

suri - the data address to load.

### Returns:

the DataSource to load the URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getMetadata

getMetadata( String suri, ProgressMonitor mon ) → java.util.Map

load the metadata for the url. This can be called independently from getDataSet, and data sources should not assume that getDataSet is called before getMetaData. Some may, in which case a bug report should be submitted. The metadata is a tree of name/value pairs, for human consumption, and used when a particular metadata model is expects.

### Parameters

suri - the data address to load.
mon - monitor, or null (None in Jython) for no feedback.

### Returns:

metadata tree created by the data source.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getTimeRangesFor

getTimeRangesFor( String surl, String timeRange, String format ) → String[]

return an array of URLs that match the spec for the time range provided. For example,

>       uri= 'https://cdaweb.gsfc.nasa.gov/istp_public/data/polar/hyd_h0/$Y/po_h0_hyd_$Y$m$d_v01.cdf?ELECTRON_DIFFERENTIAL_ENERGY_FLUX'
>       xx= getTimeRangesFor( uri, '2000-jan', '$Y-$d-$m' )
>       for x in xx:
>         print x

### Parameters

surl - an Autoplot uri with an aggregation specifier.
timeRange - a string that is parsed to a time range, such as "2001"
format - format for the result, such as "%Y-%m-%d"

### Returns:

a list of URLs without the aggregation specifier.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getTimeSeriesBrowse

getTimeSeriesBrowse( org.autoplot.datasource.DataSource ds ) → org.autoplot.datasource.capability.TimeSeriesBrowse

get the TimeSeriesBrowse capability, if available. Null (None) is returned if it is not found.

### Parameters

ds - the data source.

### Returns:

the TimeSeriesBrowse if available, or null (None)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## guardedSplit

guardedSplit( String s, char delim, char exclude1, char exclude2 ) → String[]

only split on the delimiter when we are not within the exclude delimiters. For example, `x=getDataSet("http://autoplot.org/data/autoplot.cdf?Magnitude&noDep=T")&y=getDataSet('http://autoplot.org/data/autoplot.cdf?BGSEc&slice1=2')&sqrt(x)`

### Parameters

s - the string to split.
delim - the delimiter to split on, for example the ampersand (&).
exclude1 - for example the single quote (')
exclude2 - for example the double quote (") Note URIs don't support these anyway.

### Returns:

the split. This is a copy of another code.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isLegacyImports

isLegacyImports( ) → boolean

return true if we should do the imports as before, where all of Autoplot is imported with each session. This is used to ease migration.

### Returns:

true if the old behavior should be used.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## listDirectory

listDirectory( String suri ) → String[]

returns an array of the files in the local or remote filesystem pointed to by suri. The files are returned without the path, and directories are marked with a trailing slash character. Windows a forward slash is still used, even though a back slash is more conventional. When the suri ends in slash, all entries in the directory are listed, and when it ends in a file glob, all matching files are returned.

>      print listDirectory( 'http://autoplot.org/data/pngwalk/' )
>       --> 'product.vap', 'product_20080101.png', 'product_20080102.png', ...
>      print listDirectory( 'http://autoplot.org/data/pngwalk/*.png' )
>       --> 'product_20080101.png', 'product_20080102.png', ...

### Parameters

suri - local or web directory.

### Returns:

an array of the files pointed to by surl.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## main

main( String[] args ) → void

### Parameters

args - a java.lang.String[]

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## popString

popString( String line ) → String

### Parameters

line - a String

### Returns:

java.lang.String
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## readConfiguration

readConfiguration( String suri ) → java.util.Map

read the preferences into a map. These are name=value pairs and anything following a pound symbol (#) is ignored. Anything before the equal sign is trimmed, so "x=2" and "x = 2" have the same interpretation. This has a number of TODOs, namely:

- allow quoted values, and hashes within quotes.
- allow defaults to be specified.
- allow ini files to be used as well.
- allow json files to be used as well.

%{PWD} is replaced with the directory of the config file.

### Parameters

suri - the location of files which are name value pairs.

### Returns:

a map of string to object.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## requireAutoplotScriptingVersion

requireAutoplotScriptingVersion( String v ) → void

throw an exception if the scripting version cannot be supported. These versions are numeric--so note that v1.7 is newer than v1.50, and for this reason versions should always be vNNN.NN.

### Parameters

v - a String

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## runInParallel

runInParallel( org.python.core.PyFunction job, java.util.List argument, ProgressMonitor mon ) → java.util.List

run the python jobs in parallel.

### Parameters

job - a python function which takes one argument
argument - list of arguments to invoke.
mon - monitor for the group of processes

### Returns:

list of results for each call of the function.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## sleep

sleep( int millis ) → void

sleep for so many milliseconds. This is introduced to avoid the import, which makes running scripts securely non-trivial.

### Parameters

millis - number of milliseconds to pause execution

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]