## org.autoplot.datasource.URISplit

Class for containing the elemental parts of a URI, and utility routines for working with URIs. We need a working definition of well-formed and colloquial URIs:

>      = well-formed URIs =
>        :?
>        :[?]
>        :
>        * they are valid URIs: they contain no spaces, etc.
>      == params ==
>        ampersand-delimited (&) list of name=value pairs, or just value.
>        vap+cdaweb:ds=ac_k0_epm&H_lo&timerange=2010-01
>      = colloquial URIs =
>        * these are Strings that can be converted into URIs.
>        * spaces in file names are converted into %20.
>        * spaces in parameter lists are converted into pluses.
>        * pluses in parameter lists are converted into %2B.
>        * note that if there are pluses but the URI is valid, then pluses may be left alone.

This routine knows nothing about the data source that will interpret the URI, so this needs to be established.

## URISplit( )

## PARAM_TIME_RANGE

time range subset.

## PARAM_TIME_RESOLUTION

## PARAM_RANK2

subset of rank 2 data. For example, columns of excel workbook or ascii table. rank2=[3,5] or rank2=Bx-Bz

## PARAM_REC_COUNT

used for the number of records to read.

## PARAM_ARG_0

first positional parameter, typically interpreted the same as PARAM_ID

## PARAM_ID

typically the dataset id.

## PARAM_FILE_POLL_UPDATES

some datasources support periodic checks to see if data sources have updated, such as: AggregatingDataSource AbstractDataSources (most of those based on files)

## vapScheme

scheme for Autoplot, if provided. e.g. vap+cdf.

## scheme

scheme for resource, e.g. "file" or "https"

## surl

the complete, modified surl. file:///home/jbf/mydata.qds this is the resource name, and doesn't contain the vapScheme.

## resourceUri

the resource that is handled by the DataSource. This may be null if surl doesn't form a valid uri.

## authority

the resource uri up to the authority, e.g. http://autoplot.org

## path

the resource uri including the path part.

## file

contains the resource string up to the query part.

## ext

the file/resource extention, like ".cdf" or ".dat".

## params

contains the parameters part, a ampersand-delimited set of parameters. For example, column=field2&rank2.

## filters

additional processes to be applied to the URI. For example, slice0(0) means slice the dataset at this point.

## resourceUriCarotPos

position of the caret after modifications to the surl are made. This is with respect to surl, the URI for the datasource, without the "vap" scheme.

## formatCarotPos

position of the caret after modifications to the surl are made. This is with respect to formatted URI, which probably includes the explicit "vap:" scheme.

## format

format( org.autoplot.datasource.URISplit split ) → String

format the URI using vapScheme, file and params. If file is missing but params is present, then return params: vap+cdaweb:ds=myds If file is present, then format with file and params: vap+cdf:file://tmp/my.cdf?myVar Else, just use the surl that is in there already. Note if split.params is non-null, it will be appended with a question mark, even if empty.

### Parameters

split - an URISplit

### Returns:

formatted URI.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( String vapScheme, String resourceUri, java.util.Map args ) → String

convenience method for creating URIs.

### Parameters

vapScheme - null or the data source scheme, such as "vap+das2server" or "vap+cdaweb"
resourceUri - null or the resource uri, such as "http://www-pw.physics.uiowa.edu/das/das2Server"
args - null or a map of arguments, including "arg_0" for a positional argument.

### Returns:

the URI. If vapScheme is null, then the URI will be implicit.

### See Also:

org.autoplot.jythonsupport#uri
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## formatParams

formatParams( java.util.Map parms ) → String

spaces and other URI syntax elements are URL-encoded. Note some calls of this routine should check for an empty string result and then set split.params=null instead of "", to avoid the extraneous question mark.

### Parameters

parms - a java.util.Map

### Returns:

"" or the parameters delimited by ampersands.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getParam

getParam( String surl, String name, String deft ) → String

convenient method for getting a parameter in the URI.

### Parameters

surl - a String
name - parameter name.
deft - default value if the parameter is not found.

### Returns:

a String
[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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## implicitVapScheme

implicitVapScheme( org.autoplot.datasource.URISplit split ) → String

return the vap scheme in split.vapScheme or the one inferred by the extension. Returns an empty string (not "vap") if one cannot be inferred. e.g: /home/jbf/myfile.jyds --> vap+jyds vap+txt:/home/jbf/myfile.csv --> vap+txt This was introduced as part of the effort to get rid of extraneous "vap:"s that would be added to URIs.

### Parameters

split - an URISplit

### Returns:

the vap scheme or empty string.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isUriEncoded

isUriEncoded( String surl ) → boolean

We need a standard way to detect if a string has already been URL encoded. The problem is we want valid URIs that are also readable, so just using simple encode/decode logic is not practical. This means:

- no spaces
- contains %[0-9][0-9]

### Parameters

surl - the URI

### Returns:

true if it appears to be encoded.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## makeAbsolute

makeAbsolute( String path, String suri ) → String

ensure that the reference, which may be relative, is absolute. NOTE this is only implemented for unix filenames. TODO: Windows. For example:

- /tmp/,foo.dat → /home/t/foo.dat
- /tmp/,/home/jbf/foo.dat → /home/jbf/foo.dat

### Parameters

path - the absolute directory.
suri - the URI, which may be relative to path.

### Returns:

the absolute path
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## makeCanonical

makeCanonical( String suri ) → String

make the URI canonical, with the vap+<ext>: prefix. This will also now sort the parameters, when this can be done.

### Parameters

suri - a String

### Returns:

"vap+cdf:file:///tmp/x.cdf"
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## makeColloquial

makeColloquial( String suri ) → String

make the URI colloquial, e.g. removing "vap+cdf:" from "vap+cdf:file:///tmp/x.cdf" URIs that do not have a resource URI are left alone.

### Parameters

suri - a URI

### Returns:

the URI, more colloquial and readable.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## maybeAddFile

maybeAddFile( String surl, int caretPos ) → org.autoplot.datasource.URISplit

add "file:/" to a resource string that appears to reference the local filesystem. return the parsed string, or null if the string doesn't appear to be from a file.

### Parameters

surl - a String
caretPos - an int

### Returns:

null or the URISplit
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parse

parse( java.net.URI uri ) → org.autoplot.datasource.URISplit

added to avoid widespread use of parse(uri.toString). This way its all being done with same code, and keep the URI abstraction.

### Parameters

uri - an URI

### Returns:

an org.autoplot.datasource.URISplit
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parse

parse( String suri ) → org.autoplot.datasource.URISplit

split the url string into components. This does not try to identify the vap scheme, since that might require interaction with the server to get mime type. This inserts the scheme "file://" when the scheme is absent. The string http://www.example.com/data/myfile.nc?myVariable is split into:

- scheme, http
- authority, http://www.example.com
- path, the directory with http://www.example.com/data/
- file, the file, http://www.example.com/data/myfile.nc
- ext, the extenion, .nc
- params, myVariable or null

### Parameters

suri - the uri to be parsed

### Returns:

the components.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parse

parse( String surl, int caretPos, boolean normalize ) → org.autoplot.datasource.URISplit

split the UI string into components, keeping track of the caret position when characters are inserted. This does not try to identify the vap scheme, since that might require interaction with the server to get mime type. This inserts the scheme "file://" when the scheme is absent. For example, the string http://www.example.com/data/myfile.nc?myVariable is split into:

- vapScheme, vap+nc
- scheme, http
- authority, http://www.example.com
- path, the directory with http://www.example.com/data/
- file, the file, http://www.example.com/data/myfile.nc
- ext, the extension, .nc or null.
- params, myVariable or null.
- filters, the fragment of the URI following hash character.

### Parameters

surl - the string to parse
caretPos - the position of the caret, the relative position will be preserved through normalization in formatCaretPos
normalize - normalize the surl by adding implicit "vap", etc.

### Returns:

the decomposed uri.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseParams

parseParams( String params ) → java.util.LinkedHashMap

Split the parameters (if any) into name,value pairs. URLEncoded parameters are decoded, but the string may be decoded already. Items without equals (=) are inserted as "arg_N"=name. This will check that each parameter is unique.

### Parameters

params - null or String containing the list of ampersand-delimited parameters.

### Returns:

the map, which will be empty when there are no params.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseParams

parseParams( String params, boolean validCheck ) → java.util.LinkedHashMap

Split the parameters (if any) into name,value pairs. URLEncoded parameters are decoded, but the string may be decoded already. Items without equals (=) are inserted as "arg_N"=name.

### Parameters

params - null or String containing the list of ampersand-delimited parameters.
validCheck - true will check to see if each param is unique, and possibly other checks in the future

### Returns:

the map, which will be empty when there are no params.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseTimeRange

parseTimeRange( String uri ) → DatumRange

Helper method to get the timerange from the URI

### Parameters

uri - a String

### Returns:

the DatumRange if "timerange=" is found, or null if not.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## putParam

putParam( String surl, String name, String value ) → String

convenient method for adding or replacing a parameter to the URI.

### Parameters

surl - any URI or web address
name - the parameter name to add
value - the parameter value to add

### Returns:

the uri with the question mark and parameter added.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## removeParam

removeParam( String surl, String[] parm ) → String

convenient method to remove a parameter (or parameters) from the list of parameters

### Parameters

surl - any URI or web address
parm - the name to remove

### Returns:

the URI with the parameter removed, and the question mark removed when no parameters remain.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setOtherSchemes

setOtherSchemes( java.util.List otherSchemes ) → void

allow parsing of script:, bookmarks:, pngwalk:, etc

### Parameters

otherSchemes - a java.util.List

### Returns:

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

## toString

toString( ) → String

### Returns:

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

## uriDecode

uriDecode( String s ) → String

convert "+" to " ", etc, by using URLDecoder and catching the UnsupportedEncodingException that will never occur. We have to be careful for elements like %Y than are not to be decoded. TODO: we need to use standard escape/unescape code, possibly changing %Y to $Y beforehand.

### Parameters

s - a String

### Returns:

a String
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## uriEncode

uriEncode( String surl ) → String

convert " " to "%20", etc, by looking for and encoding illegal characters. We can't just aggressively convert...

### Parameters

surl - the URI

### Returns:

the URL-encoded URI
[search for examples] [view on GitHub] [view on old javadoc] [view source]