Dashboard > GridGain User Guide > Table Of Contents > Developers Guide > Deployment SPI > GridUriDeploymentSpi
GridGain User Guide
GridUriDeploymentSpi
Added by user-1-ds, last edited by ghost on Mar 20, 2008  (view change)
Labels: 
(None)


Click on Javadoc link to open Javadoc documentation.

Package

org.gridgain.grid.spi.deployment.uri Javadoc

Description

Implementation of Deployment SPI which can deploy tasks from different sources like file system folders, FTP, email and HTTP. There are different ways to deploy tasks in grid and every deploy method depends on selected source protocol. This SPI is configured to work with a list of URI's. Every URI contains all data about protocol/transport plus configuration parameters like credentials, scan frequency, and others.

When SPI establishes a connection with a URI, it downloads deployable units to the temporary directory in order to prevent it from any changes while scanning. Use method setTemporaryDirectoryPath(String) Javadoc to set custom temporary folder for downloaded deployment units.

SPI tracks all changes of every given URI. This means that if any file is changed or deleted, SPI will re-deploy or delete corresponding tasks. Note that the very first call to findTask(String) Javadoc is blocked until SPI finishes scanning all URI's at least once.

There are several deployable unit types supported:

  • GAR file.
  • Local disk folder with structure of unpacked GAR file.
  • Local disk folder containing only compiled Java classes.

GAR file

GAR file is a deployable unit. GAR file is based on ZLIB compression format like simple JAR file and its structure is similar to WAR archive. GAR file has .gar extension.

GAR file structure (file or directory ending with .gar):

META-INF/
        |
         - gridgain.xml
         - ...
lib/
   |
    -some-lib.jar

    - ...
xyz.class
...
  • META-INF/ entry may contain gridgain.xml file which is a task descriptor file. The purpose of task descriptor XML file is to specify all tasks to be deployed. This file is a regular Spring XML definition file. META-INF/ entry may also contain any other file specified by JAR format.
  • lib/ entry contains all library dependencies.
  • Compiled Java classes must be placed in the root of a GAR file.

GAR file may be deployed without descriptor file. If there is no descriptor file, SPI will scan all classes in archive and deploy those that implement GridTask interface. Use GridTaskAdapter Javadoc adapter for convenience when deploying grid tasks.

By default, all downloaded GAR files that have digital signature in META-INF folder will be verified and and deployed only if signature is valid.

URI

This SPI uses a hierarchical URI definition. For more information about standard URI syntax refer to java.net.URI documentation:

[scheme:][//authority][path][?query][#fragment]

Every URI defines its own deployment repository which will be scanned for any changes. URI itself has all information about protocol, connectivity, scan intervals and other parameters.

URI's may contain special characters, like spaces. If encodeUri flag is set to true (see GridUriDeploymentSpi.setEncodeUri(boolean) Javadoc ), then URI 'path' field will be automatically encoded. By default this flag is set to true.

Protocols

Following protocols are supported in SPI:

  • ftp:// - File transfer protocol
  • pop3:// - POP3 mail protocol
  • pop3s:// - Secured POP3 mail protocol
  • imap:// - IMAP mail protocol
  • imaps:// - Secured IMAP mail protocol
  • file:// - File protocol
  • http:// - HTTP protocol
  • https:// - Secure HTTP protocol

In addition to SPI configuration parameters, all necessary configuration parameters for selected URI should be defined in URI. Different protocols have different configuration parameters described below. Parameters are separated by ';' character.

FTP

For FTP protocol SPI will scan and download only GAR files from source directory defined in URI. SPI doesn't scan FTP folders recursively. The following parameters are supported for ftp:// protocol:

Parameter Description Optional Default
freq FTP location scan frequency in milliseconds. Yes 300000 ms specified in DFLT_FTP_SCAN_FREQUENCY Javadoc .
username:password FTP username and password specified in standard URI server-based authority format. No —

Here is an example of an FTP URI that connects identified as username:password to localhost on port 21, with initial path set to gridgain/deployment:

ftp://username:password;freq=10000@localhost:21/gridgain/deployment

Mail

For Mail protocols this SPI scans mail inboxes for new mail messages looking for GAR file attachments. Once a mail message with GAR file is found, it will be deployed. Mail protocols works with following schemes: pop3, pop3s, imap, and imaps.

The following parameters are supported for pop3:// or pop3s:// protocols:

Parameter Description Optional Default
freq Main inbox scan frequency in milliseconds. Yes 300000 ms specified in DFLT_MAIL_SCAN_FREQUENCY Javadoc .
username:password Mail username and password specified in standard URI server-based authority format. No —
auth Connection type. Can be one of the following:
  • none
  • ssl
  • starttls
 Yes none
subj Subject filter for mail messages used by SPI. All messages with different subjects will be ignored. Yes grid.email.deploy.msg specified in DFLT_MAIL_SUBJECT Javadoc

The following example demonstrates Mail URI that will connect user identified as username:password with authorization set to none to host pop.gmail.com on port 110 scanning inbox every 120000 milliseconds (2 minutes).

pop3://username:password;auth=ssl;freq=120000@pop.gmail.com:995

HTTP

For HTTP protocols this SPI scans and downloads GAR files from source directory defined in URI. SPI does not scan HTTP folders recursively. Only HTTP links that end with .gar extension will be downloaded. HTTP protocol works with scheme http and https.

The following parameters are supported for http:// or https:// protocols:

Parameter Description Optional Default
freq HTTP directory scan frequency in milliseconds. Yes 300000 ms specified in DFLT_HTTP_SCAN_FREQUENCY Javadoc .
username:password Optional HTTP directory username and password specified in standard URI server-based authority format. Yes —

The following example will scan gridgain/deployment folder with on site www.mysite.com using authentication username:password every 10000 milliseconds.

http://username:password;freq=10000@www.mysite.com:110/gridgain/deployment

File

For this protocol SPI will scan folder specified by URI on file system and download any GAR files or directories that end with .gar from source directory defined in URI. For file system URI must have scheme equal to file.

Following parameters are supported for file:// protocol:

Parameter Description Optional Default
freq File directory scan frequency in milliseconds. Yes 5000 ms specified in DFLT_DISK_SCAN_FREQUENCY Javadoc .

The following example will scan c:/Program files/gridgain/deployment folder on local box every 5000 milliseconds. Note that since path has spaces, setEncodeUri(boolean) parameter must be set to true (which is default behavior).

file://freq=5000@localhost/c:/Program files/gridgain/deployment

Configuration

GridUriDeploymentSpi Javadoc has the following optional configuration parameters (there are no mandatory parameters):

  • Temporary directory path where scanned GAR files and directories are copied to (see setTemporaryDirectoryPath(String)).
  • List of URIs to scan (see GridUriDeploymentSpi.setUriList(List)). If not specified, then URI specified by DFLT_DEPLOY_DIR is used.
  • Flag to control encoding of the 'path' portion of URI (see setEncodeUri(boolean)).

The following configuration parameters can be used to configure GridUriDeploymentSpi

Setter Method Description Optional Default
setTemporaryDirectoryPath(String) Javadoc Sets absolute path to temporary directory which will be used by deployment SPI to keep all deployed classes in. Yes System property java.io.tmpdir value provided by java.lang.System.getProperty(java.lang.String).
setUriList(List<String>) Javadoc Sets list of URI which point to path with GAR files and which should be scanned by SPI for the new tasks. Yes List with "file://${GRIDGAIN_HOME}/work/deployment/file" element.
setEncodeUri(boolean) Javadoc Indicates that URI 'path' part must be encoded before usage. Encoding means replacing all occurrences of space with '%20', percent sign with '%25' and semicolon with '%3B'. Yes true which means all URIs 'path' parts should be encoded.


For more information about using Spring framework for configuration click here.

Examples

GridUriDeploymentSpi needs to be explicitely configured to override default local deployment SPI.

GridUriDeploymentSpi deploySpi = new GridUriDeploymentSpi();

GridConfigurationAdapter cfg = new GridConfigurationAdapter();

List<String> uris = new ArrayList<String>(5);

uris.add("http://www.site.com/tasks");
uris.add("ftp://ftpuser:password;freq=10000@localhost:21/gg-test/deployment");
uris.add("file://freq=20000@localhost/c:/Program files/gg-deployment");
uris.add("pop3://test%20user:test%20password;subj=grid.deploy.subj;auth=none@pop.mail.ru:110");

// Set URIs.
deploySpi.setUriList(uris);

// Override temporary directory path.
deploySpi.setTemporaryDirectoryPath("c:/tmp/grid");

//  Override default deployment SPI.
cfg.setDeploymentSpi(deploySpi);

//  Start grid.
GridFactory.start(cfg);

or from Spring configuration file

<bean id="grid.custom.cfg" class="org.gridgain.grid.GridConfigurationAdapter" singleton="true">
        ...
        <property name="deploymentSpi">
            <bean class="org.gridgain.grid.spi.deployment.uri.GridUriDeploymentSpi">
                <property name="temporaryDirectoryPath" value="c:/tmp/grid"/>
                <property name="uriList">
                    <list>
                        <value>http://www.site.com/tasks</value>
                        <value>ftp://ftpuser:password;freq=10000@localhost:21/gg-test/deployment</value>
                        <value>file://freq=20000@localhost/c:/Program files/gg-deployment</value>
                        <value>pop3://test%20user:test%20password;subj=grid.deploy.subj;auth=none@pop.mail.ru:110</value>
                    </list>
                </property>
            </bean>
        </property>
        ...
</bean>

GAR file descriptor example.

GAR descriptor (gridgain.xml) example below demonstrates how a user can declare tasks to deploy in a Spring 2.x configuration file. It should be provided in META-INF folder inside of GAR directory structure. Keep in mind that GAR descriptor is optional and if not provided, then all GAR classes will be scanned and all grid task classes that implement GridTask Javadoc interface will be deployed.

<!--
    Spring-based GAR descriptor.
-->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd">
    <description>Gridgain Spring GAR descriptor.</description>

    <!--
        List of task class names to deploy.
    -->
    <util:list id="tasks">
        <value>com.user.logic.GridTask1</value>
        <value>com.user.logic.GridTask2</value>
    </util:list>
</beans>
Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.2.10 Build:#528 Nov 29, 2006) - Bug/feature request - Contact Administrators