ESE Routines > ESEServer

# ESEServer

The ESEServer class provides the ability to:

- Introspect an ESE installation for its catalog
- Get a task by URI
- Get a task by name or pattern
- Upload files
- Download files

## Methods

- ESEServer::About
- ESEServer::DownloadFile
- ESEServer::FindTask
- ESEServer::GetCatalog
- ESEServer::GetTask
- ESEServer::Ping
- ESEServer::UploadFile

## Examples

### Example 1

The full hierarchy of tasks can be introspected, starting with the ESECatalog. In this example we start the process of enumerating all folders, services and tasks by using an ESEServer object to get the catalog. Folders and services can be acquired by using the catalog object's methods. Similarly, tasks can be acquired from ESEService objects.

Server = ESE.GetServer( 'localhost', 8181 )

Catalog = Server.GetCatalog()

### Example 2

The ESEServer class has two convenience methods for finding tasks: FindTask() and GetTask(). If the URI of a task is not known then the task can be searched for using findTask(). This is also good if the task ever moves within the folder and services hierarchy.

Server = ESE.GetServer( 'localhost', 8181 )

Task = Server.FindTask( 'ese_addition' )

Regular expressions can also be used. In this example, all tasks with the substring 'ortho' in their name are found:

Server = ESE.GetServer( 'localhost', 8181 )

Task = Server.FindTask( 'ortho', /REGEX )

### Example 3

If the URI to a task is known, then GetTask() can be used to more directly specify and retrieve an ESETask object. Since there is a fixed root ("ese") and only one catalog (defaults to "services"), they are not specified.

Server = ESE.GetServer( 'localhost', 8181 )

Task = Server.GetTask( 'SyncService/ese_addition' )

When a service is in a folder, its tasks can be retrieved this way:

Server = ESE.GetServer( 'localhost', 8181 )

Task = Server.GetTask( 'MyFolder/MySubFolder/MyService/myFunTask' )

## Properties

### HOST (Get)

The name or IP address of the machine that is hosting the ESE server.

### PORT (Get)

The port number that the ESE server is listening on.

### ROOT (Get)

The root endpoint for all ESE requests. This value is always 'ese'.

### URI (Get)

The URI up to and including the host, port, and root (for example, `http://host:port/ese`).

# ESEServer::About

This method returns a hash that gives version information for ESE, IDL, ENVI, LiDAR, Mongoose, and SQLite.

## Example

Server = ESE.GetServer( 'localhost', 8181 )

info = Server.About()

## Syntax

Result = Obj.[ESEServer::]About()

## Return Value

Returns a hash with the following keys and values:

Key | Example Value
--- | ---
ESE | Version 5.2.1
License Expiration Date | 1-apr-2015
Maximum Concurrent Jobs | 4
IDL Version | 8.4.1 (Jan 18, 2014)
IDL Platform | unix
ENVI Version | 5.2.1 (Jan 18, 2014)
LiDAR Version | unavailable
Mongoose Version | 5.4
SQLite Version | 3.7.13

This method returns !null on error.

## Arguments

None.

## Keywords

None.

# ESEServer::DownloadFile

This method downloads the resource specified by the given URL to the given file path. An array of URLs and matching files can be provided. The URLs must be valid and the file paths must be new files in writable directories.

## Example

This example downloads the file previously uploaded in the ESE::uploadFile example. Note that the destination path must be updated to be valid.

Server = ESE.GetServer( 'localhost', 8181 )

Server.DownloadFile( 'http://localhost:8181/docroot/ese/data_upload/boulder.tif', 'C:\Users\me\Desktop\boulder.tif' )

## Syntax

Obj.[ESEServer::]DownloadFile, URL, File

## Return Value

None.

## Arguments

### URL

The URL of the file to download. The ESE server can only download files that exist underneath its "docroot" directory. This argument can be an array of URLs. In that case, the File argument should be an array of corresponding destination file paths.

### File

The destination to download the file to. This argument can be an array of file paths.

## Keywords

None.

# ESEServer::FindTask

This method searches for the given task and returns an array of ESETask objects. If the REGEX keyword is specified, then matches are performed using the name as a regular expression. The search is case insensitive.

## Example

Server = ESE.GetServer( 'localhost', 8181 )

Task = Server.FindTask( 'ortho', /REGEX)

## Syntax

Task = Obj.[ESEServer::]FindTask( Name [, /REGEX ] )

## Return Value

Returns one or more ESETask objects. If more than one match is found then the return value is an array of ESETask objects. If there is a communications error with the server then an error is thrown.

## Arguments

### Name

The name of the task to search for. Matches are case-insensitive.

## Keywords

### REGEX

Set this keyword to perform matching using Name as a regular expression. Matches are case-insensitive.

# ESEServer::GetCatalog

This method returns an object that represents the server's catalog. There is only one.

## Example

Server = ESE.GetServer( 'localhost', 8181 )

Catalog = Server.GetCatalog()

## Syntax

Catalog = Obj.[ESEServer::]GetCatalog()

## Return Value

This method returns an ESECatalog object.

## Arguments

None.

## Keywords

None.

# ESEServer::GetTask

This method returns the ESETask object at the given relative URI, which must start with a folder or service. The root and catalog are implied and must not be specified. Namely, the URI should be [folders/]service/task.

## Example

Server = ESE.GetServer( 'localhost', 8181 )

Task = Server.GetTask( 'SyncService/ese_addition' )

## Syntax

Task = Obj.[ESEServer::]GetTask( URI )

## Return Value

Returns an ESETask object that represents the specified task. If the relative URI is invalid then !null is returned.

## Arguments

### URI

A partial URI that is relative to the server's catalog. The server's root and catalog (typically 'ese' and 'services') are implied. The relative URI must begin with the folder or service that follows the catalog.

## Keywords

None.

# ESEServer::Ping

This method checks whether the server is alive, returning !true or !false.

## Example

Server = ESE.GetServer( 'localhost', 8181 )

isAlive = Server.Ping()

## Syntax

Result = Obj.[ESEServer::]Ping()

## Return Value

This method returns !true if the server is responsive; otherwise, it returns !false.

## Arguments

None.

## Keywords

None.

# ESEServer::UploadFile

This method uploads the specified file or files to ESE's "docroot/ese/data_upload" directory. The return value is the URI of the uploaded file (or an array, as appropriate). If the file already exists at the specified destination then it is overwritten. If there is a failure then an error is thrown.

## Example

file = filepath( 'boulder.tif', subdir = [ 'examples', 'data' ] )

Server = ESE.GetServer( 'localhost', 8181 )

uri = Server.UploadFile( file )

## Syntax

URIs = Obj.[ESEServer::]UploadFile( Files )

## Return Value

Returns the URI of the uploaded file or an array of URIs if an array of files was specified.

## Arguments

### Files

A scalar or array of file paths. Each specified file is uploaded to the "docroot/ese/data_upload" directory on the server and a URI to the file is returned for convenience.

## Keywords

None.

## Version History

IDL 8.4.1 | Introduced

## See Also

ESE, ESECatalog, ESETask