NAME

HeliosX::Job::JSON - Helios::Job subclass using JSON to specify job arguments

SYNOPSIS

 # In your Helios::Service class:
 package MyService;
 use parent 'Helios::Service';
 use HeliosX::Job::JSON;
 
 sub JobClass { 'HeliosX::Job::JSON' }
 
 sub run {
        ... run code here ... 
 }
 
 1;
 
 # In your job submission code, use 
 # HeliosX::Job::JSON just like Helios::Job.
 my $config = Helios::Config->parseConfig();
 my $arg_json = qq/{ "args" : { "arg1": "value1", "arg2": "string2" } }/; 
 my $job = HeliosX::Job::JSON->new();
 $job->setConfig($config);
 $job->setJobType('MyService');
 $job->setArgString($arg_json);
 my $jobid = $job->submit();

 # You may also specify the config, jobtype, 
 # and argument string to the constructor.
 my $arg_json = qq/{ "args" : { "arg1": "value1", "arg2": "string2" } }/; 
 my $job = HeliosX::Job::JSON->new(
        config    => $config,
        jobtype   => 'MyService',
        argstring => $arg_json
 );
 my $jobid = $job->submit();
 
 # Also, if you omit config, HeliosX::Job::JSON will 
 # use Helios::Config to get the config hash.
 # If you specify the jobtype in the JSON object string,
 # you do not have to specify a specific jobtype
 my $arg_json = qq/{ "jobtype" : "MyService", "args" : { "arg1": "value1", "arg2": "string2" } }/; 
 my $job = HeliosX::Job::JSON->new(
        argstring => $arg_json
 );
 my $jobid = $job->submit();

 # Or use the included heliosx_job_json_submit command. 
 heliosx_job_json_submit --jobtype=MyService --args='{ "args" : { "arg1": "value1", "arg2": "string2" } }'

DESCRIPTION

HeliosX::Job::JSON is a Helios::Job subclass allowing you to specify Helios job arguments in JSON format instead of Helios's default XML format. If parts of your application or system use the JSON data format, or your Helios job arguments are difficult to express in XML, you can change your Helios service to use HeliosX::Job::JSON to specify your job arguments in JSON.

JSON JOB ARGUMENT FORMAT

Helios job argument JSON should describe a JSON object in the format:

 {
     "jobtype" : "<Helios jobtype name>",
     "args" : {
         "<arg1 name>" : "<arg1 value>",
         "<arg2 name>" : "<arg2 value>",
         ...etc...
     }
 }

Your JSON object string will define a "jobtype" string and an "args" object. The name and value pairs of the args object will become the job's argument hash. For example:

 {
     "jobtype" : "MyService",
     "args": {
              "arg1"          : "value1",
              "arg2"          : "value2",
              "original_file" : "photo.jpg",
              "size"          : "125x125"
             }
 }

The jobtype value is optional if you specify a jobtype another way i.e. using the --jobtype option with heliosx_job_json_submit or using HeliosX::Job::JSON's setJobType() method.

NOTE ABOUT METAJOBS

HeliosX::Job::JSON does not yet support Helios metajobs. Specifying metajob arguments in JSON may be supported in a future release.

METHODS

new()

The HeliosX::Job::JSON new() constructor overrides Helios::Job's constructor to allow you to specify the Helios config hash, jobtype, and argument string without making separate subsequent method calls to setConfig(), setJobType(), or setArgString().

parseArgs()

HeliosX::Job::JSON's parseArgs() method is much simpler than Helios::Job's parseArgs() method because JSON's object format is very close to Perl's concept of a hash.

parseArgString($json_string)

The parseArgString() method does the actual parsing of the JSON object string into the Perl hash using JSON::Tiny. If parsing fails, the method will throw a HeliosX::Job::JSON::Error exception.

submit()

HeliosX::Job::JSON's submit() method overrides Helios::Job's submit() to allow specifying the jobtype via the JSON object instead of requiring a separate call to setJobType(). If the jobtype wasn't explicitly specified and submit() cannot determine the jobtype from the JSON object, it will throw a HeliosX::Job::JSON::Error exception.

Also, if the config hash was not explicitly specified with either a config parameter to new() or the setConfig() method, submit() will use Helios::Config->parseConfig() to get the collective database's dsn, user, and password values in the [global] section of the Helios configuration.

If job submission is successful, this method will return the new job's jobid to the calling routine.

AUTHOR

Andrew Johnson, <lajandy at cpan dot org>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Logical Helion, LLC.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. See the included LICENSE file for details.

WARRANTY

This software comes with no warranty of any kind.

cpanm HeliosX::Job::JSON

perl -MCPAN -e shell
install HeliosX::Job::JSON