/*
 * $Id: jasmine.idl,v 1.36 2002/03/25 18:28:56 akhan Exp $
 *
 * Copyright (c) 1999 Oracle Corp. All Rights Reserved.
 */

//
// General definitions
//
module oracle 
{
  module reports 
  {
    //
    // General definitions
    //
    typedef sequence<octet>     ByteArray;
    typedef sequence<wstring>   StrArray;
    typedef sequence<short>     ShortArray;
    typedef sequence<long>      LongArray;
    typedef sequence<long long> LongLongArray;

    //
    // Version number
    //
    const string VERSION = "9.0.2.0.1";

    struct RWError
    {
      long    errorCode;   // error code
      wstring errorString; // error string
      wstring moduleName;  // module name where error occur
    };

    typedef sequence<RWError> RWErrorChain;

    exception RWException
    {
      RWErrorChain errorChain;
    };

    struct Repeat
    {
      wstring schedule;   // textual representation of schedule
      short   unit;       // repeat unit, see constants REPEAT_UNIT_* below
      long    interval;   // overload to represent <weekday> and <day>
    };

    struct Retry
    {
      short maxRetryTimes; // maximum times to retry after failure
      short curRetryTimes; // current retry times
      long  waitPeriod; // wait period after failure
      short unit;       // the unit for waitPeriod, see constants
                        // REPEAT_UNIT_* below
    };

    struct JobStatus
    {
      short  status;      // see constants STATUS_* defined below
      long   extraStatus; // Can be constants RUN_STATUS_* defined below
                          // or the page number currently formatting
                          // or the remote job id if the job has been transfered
      wstring serverName; // the server name which the job is actually on
      RWErrorChain errorChain; // error chain for whole job
    };

    struct JobDest
    {
      short          format;        // job output format
      wstring        destype;       // job destination type
      wstring        desname;       // job destination name
      RWErrorChain   errorChain;    // error chain for this destination
    };

    struct JobInfo
    {
      long           id;            // job id
      short          queue;         // job queue, see QUEUE_*
      wstring        name;          // job name
      wstring        type;          // job type: "report", "jsp", "discovery"
      wstring        owner;         // job owner, or username
      sequence<JobDest> dests;      // array of job destinations
      wstring        mimetype;      // job output mimetype
      JobStatus      status;        // job status
      long           parentId;      // this is only valid for finished schedule
                                    // job. It point to scheduled job
      long long      timeQueued;    // time enqueued
      long long      timeStarted;   // time started to run
      long long      timeFinished;  // time finished running
      long long      timeLastRun;   // time of last run (for scheduled job)
      long long      timeNextRun;   // time of next run (for scheduled job)
      Repeat         repeatInterval; // repeat interval (for repeated job)
    };

    typedef sequence<JobInfo> QueueInfo;

    interface JobConstants
    {
      //////////////////////
      // Constants for Job
      //////////////////////

      // job output formats
      // First 7 constants has to be same as ZRCCT_FORMAT_* so that
      // the c-engine doesn't need to convert the constants
      const short FORMAT_UNKNOWN    = 0;
      const short FORMAT_ASCII      = 1;
      const short FORMAT_HTML       = 2;
      const short FORMAT_PDF        = 3;
      const short FORMAT_BITMAP     = 4;
      const short FORMAT_RTF        = 5;
      const short FORMAT_XML        = 6;
      const short FORMAT_DELIMITED  = 7;
      const short FORMAT_GIF        = 8;
      const short FORMAT_HTMLCSS    = 9;

      // job queue type
      const short QUEUE_CURRENT      = 0;  // job is running or to be run
                                           // immediately
      const short QUEUE_FUTURE       = 1;  // job to be run in future
      const short QUEUE_PAST         = 2;  // passed job

      // job repeat units
      const short REPEAT_UNIT_NONE      = 0;  // job does not repeat
      const short REPEAT_UNIT_MINUTES   = 1;  // every <interval> munites
      const short REPEAT_UNIT_DAYS      = 2;  // every <interval> days
      const short REPEAT_UNIT_MONTHS    = 3;  // every <interval> months
      const short REPEAT_UNIT_FIRST     = 4;
                                  // every 1st <weekday> of each month
      const short REPEAT_UNIT_SECOND    = 5;
                                  // every 2nd <weekday> of each month
      const short REPEAT_UNIT_THIRD     = 6;
                                  // every 3rd <weekday> of each month
      const short REPEAT_UNIT_FOURTH    = 7;
                                  // every 4th <weekday> of each month
      const short REPEAT_UNIT_FIFTH     = 8;
                                  // every 5th <weekday> of each month
      const short REPEAT_UNIT_SUNDAY    = 9;
                                  // last sunday of each month before <day>th
      const short REPEAT_UNIT_MONDAY    = 10;
                                  // last monday of each month before <day>th
      const short REPEAT_UNIT_TUESDAY   = 11;
                                  // last tuesday of each month before <day>th
      const short REPEAT_UNIT_WEDNESDAY = 12;
                                  // last wednesday of each month before <day>th
      const short REPEAT_UNIT_THURSDAY  = 13;
                                  // last thursday of each month before <day>th
      const short REPEAT_UNIT_FRIDAY    = 14;
                                  // last friday of each month before <day>th
      const short REPEAT_UNIT_SATURDAY  = 15;
                                  // last saturday of each month before <day>th
      const short REPEAT_UNIT_WEEKDAY   = 16;
                                  // last weekday of each month before <day>th
      const short REPEAT_UNIT_WEEKEND   = 17;
                                  // last weekend of each month before <day>th

      // job queue info masks: do not change the order here since it is in sync
      //  with the internal jni code.
      const long QUEUE_INFO_CURRENTJOBS   = 0x0000001; // row
      const long QUEUE_INFO_SCHEDULEDJOBS = 0x0000002; // row
      const long QUEUE_INFO_PASTJOBS_CNT  = 0x0000004; // row, use counter
      const long QUEUE_INFO_PASTJOBS_DAYS = 0x0000008; // row, use cut off day
      const long QUEUE_INFO_FILTERUSER    = 0x0000010; // row, for current user
      const long QUEUE_INFO_JOBQUEUE      = 0x0000020; // column
      const long QUEUE_INFO_JOBNAME       = 0x0000040; // column
      const long QUEUE_INFO_JOBOWNER      = 0x0000080; // column
      const long QUEUE_INFO_FORMAT        = 0x0000100; // column
      const long QUEUE_INFO_DESTYPE       = 0x0000200; // column
      const long QUEUE_INFO_DESNAME       = 0x0000400; // column
      const long QUEUE_INFO_JOBSTATUS     = 0x0000800; // column
      const long QUEUE_INFO_TIMEQUEUED    = 0x0001000; // column
      const long QUEUE_INFO_TIMESTARTED   = 0x0002000; // column
      const long QUEUE_INFO_TIMEFINISHED  = 0x0004000; // column
      const long QUEUE_INFO_TIMELASTRUN   = 0x0008000; // column
      const long QUEUE_INFO_TIMENEXTRUN   = 0x0010000; // column
      const long QUEUE_INFO_REPINTERVAL   = 0x0020000; // column
      const long QUEUE_INFO_MASTERJOBID   = 0x0040000; // column
      const long QUEUE_INFO_TNSNAME       = 0x0080000; // column
      const long QUEUE_INFO_JOBTYPE       = 0x0100000; // column
      const long QUEUE_INFO_JOBMIMETYPE   = 0x0200000; // column
      const long QUEUE_INFO_PASTJOBS_SUCC = 0x1000000; // row, succeeded jobs
      const long QUEUE_INFO_PASTJOBS_FAIL = 0x2000000; // row, failed jobs
      const long QUEUE_INFO_CLUSTER       = 0x8000000; // row, include cluster

      // job status
      const short STATUS_UNKNOWN    = 0;  // no such job
      const short STATUS_ENQUEUE    = 1;  // waiting in the queue
      const short STATUS_OPENING    = 2;  // opening the report
      const short STATUS_RUNNING    = 3;  // running a report
      const short STATUS_FINISHED   = 4;  // has finished successfully
      const short STATUS_TERMINATED = 5;  // terminated with error
      const short STATUS_CRASHED    = 6;  // engine crashed
      const short STATUS_CANCELED   = 7;  // canceled upon user request
      const short STATUS_SHUTDOWN   = 8;  // canceled as server is shutdown
      const short STATUS_RETRY      = 9;  // has failed and waiting for retry
      const short STATUS_OUTPUT     = 10; // sending output
      const short STATUS_TRANSFERED = 11; // the job has been transfered to
                                          // another server in the cluster
      const short STATUS_VOIDFINISHED = 12; // finished job but voided
      const short STATUS_ERRORFINISHED = 13; // finished but some distribution
                                             // failed   

      // job running status
      const long  RUN_STATUS_INITIALIZE_REPORT     = -1;
      const long  RUN_STATUS_BEFORE_REPORT_TRIGGER = -2;
      const long  RUN_STATUS_BETWEEN_PAGE_TRIGGER  = -3;
      const long  RUN_STATUS_AFTER_REPORT_TRIGGER  = -4;
      const long  RUN_STATUS_BEFORE_FORM_TRIGGER   = -5;
      const long  RUN_STATUS_AFTER_FORM_TRIGGER    = -6;

      // some of job running error codes client might want to know
      // mainly for zrc backward compatibility
      const long  RUN_ERROR_GENERIC      = 50000; // generic running error
      const long  RUN_ERROR_INITIAL      = 50001; // server is initializing
      const long  RUN_ERROR_SHUTDOWN     = 50002; // server is shuting down
      const long  RUN_ERROR_BADCMDLINE   = 50003; // bad command line
      const long  RUN_ERROR_NOREPORT     = 50004; // no report in command line
      const long  RUN_ERROR_NOUSERID     = 50005; // no userid in command line
      const long  RUN_ERROR_BADSCHEDULE  = 50006; // bad schedule argument
      const long  RUN_ERROR_BADTOLERANCE = 50007; // bad tolerance argument

      const long  SUCC_SUBMIT            = 50008; // successfully submitted
      const long  SUCC_RUN               = 50009; // successfully run
    };

    // forward definition
    module server
    {
      interface ServerClass;
    };

    module utility
    {
      /////////////////////////////////////////////////////////////////////////
      // Interface: Trace
      // The generic trace interface to log trace messages.
      /////////////////////////////////////////////////////////////////////////
      interface Trace
      {

        //----------------------------------------------------------
        // Trace flags
        // following are come from earlier version of runtime
        // The Trace Masks defined here must match the order and 
        // value defined in the C-Engine. Please refer rxtrce.h
        // for the values and masks of the C-Engine's trace info.
        // Any new mask defined here must also have an equivalent 
        // entry in rxtrce.h
        
        const unsigned long ERROR     = 0x01;
        const unsigned long PRF       = 0x02;
        const unsigned long BRK       = 0x04;
        const unsigned long APP       = 0x08;
        const unsigned long PLS       = 0x10;
        const unsigned long SQL       = 0x20;
        const unsigned long TMS       = 0x40;
        const unsigned long DST       = 0x80;
        // following are new for jasmine
        const unsigned long LOG       = 0x0100;
        const unsigned long INFO      = 0x0200;
        const unsigned long DEBUG     = 0x0400;
        const unsigned long WARNING   = 0x0800;
        const unsigned long STATE     = 0x1000;
        const unsigned long EXCEPT    = 0x2000;
        // The 31st bit is made reserved to indicate start and end of profiling.
        // The 31st bit will be set to indicate start of profiling
        const unsigned long START_PRF = (0x40000000 | PRF);
        const unsigned long END_PRF   = (0x00000000 | PRF);

        // Changed to discard the 31st bit ( reserved for Profiling start / end )
        // from the ALL list.
        // public static final int ALL    = 0xffffffff;
        const unsigned long ALL       = 0xbfffffff;

        const string TRACE_PRF = "trace_prf";
        const string TRACE_BRK = "trace_brk";
        const string TRACE_APP = "trace_app";
        const string TRACE_PLS = "trace_pls";
        const string TRACE_SQL = "trace_sql";
        const string TRACE_TMS = "trace_tms";
        const string TRACE_DST = "trace_dst";
        const string TRACE_LOG = "trace_log";
        const string TRACE_ERR = "trace_err";
        const string TRACE_INF = "trace_inf";
        const string TRACE_DBG = "trace_dbg";
        const string TRACE_WRN = "trace_wrn";
        const string TRACE_STA = "trace_sta";
        const string TRACE_EXC = "trace_exc";
        const string TRACE_ALL = "trace_all";

        const string TRACE_REPLACE = "trace_replace";
        const string TRACE_APPEND  = "trace_append";

        const string TRACE_EXTENSION  = ".trc";
        const string LOG_EXTENSION = ".log";

        // Write a trace message
        void writeln(
            in long     traceFlag,  // - Trace flag, the value can be any
                                    // combination of the flags defined above.
            in string   location,   // - The location of the code segment from
                                    // where it is called.
            in long     messageID,  // - ID of the message in the resource
                                    // bundle file.
            in wstring  message     // - The trace message.
        );
      };
    }; // end - module utility

    module engine
    {
      interface EngineReport;

      ///////////////////////////////////////////////////////////////////////
      // Engine object that handles communication between engine and server
      ///////////////////////////////////////////////////////////////////////
      interface EngineClass
      {
        // engine state constants
        const short STATE_INITIAL  = 0; // engine is initializing itself
        const short STATE_READY    = 1; // engine is ready to serve
        const short STATE_RESERVED = 2; // engine is reserved for use
        const short STATE_RUNNING  = 3; // engine is running a job
        const short STATE_SHUTDOWN = 4; // engine is shuting down itself
        const short STATE_IDLE     = 5; // engine is assigned to client, but
                                        // client does nothing in engine

        ///////////////////////////////////////////////////////////////////////
        // set (send) report definition file (rdf, xml, or any dependent file)
        // into the engine. Client could call this method multiple times to set
        // multiple files
        void setFile(
          in string accessKey,     // engine access key
          in wstring fileName,     // file name
          in wstring fileFormat,   // file format, such as "xml"
          in ByteArray fileStream, // content of the file
          in boolean main          // indicate whether the file is main
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // set report command line, usually called by server only
        void setCommandLine(
          in string accessKey,    // engine access key
          in long jobId,          // job id
          in wstring commandLine   // command line to be run
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // run the report synchronously
        void run(
          in string accessKey     // engine access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Cancel currently running job or scheduled job
        void cancel(
          in string accessKey     // engine access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Ping the engine to test if engine is alive
        void ping(
          in string accessKey       // engine access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Change job id
        // When a user cancel a job in server, the job may be used by several
        // duplicated jobs, so the cancellation should only change the job id
        // from canceled one to the next one in duplicated chain
        void changeJobId(
          in string accessKey,
          in long jobId
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Shut down engine
        oneway void shutdown(
          in string accessKey      // engine access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Create a empty report
        // @JSP support
        // Bug2002616 Add ImageURl argument
        EngineReport createReport(
          in string accessKey,     // engine access key,
          out long long jniReport,  // jni report object handle
          in wstring imageURL       // imageURL from rwclient.cfg
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get environment variables accessable from engine
        void getEnvs(
          in string accessKey,     // connection object access key
          out StrArray envNames,   // environment names
          out StrArray envValues   // environment values
        ) raises (RWException);
      };

      /////////////////////////////////////////////////////////////////////
      // Report object in the engine
      /////////////////////////////////////////////////////////////////////
      interface EngineReport
      {
        ///////////////////////////////////////////////////////////////////////
        // Cleanup the engine after jsp operation
        // should be called before release()
        // @JSP support
        void doneReport(
          in string accessKey      // engine access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Create report level cursor
        // @JSP support
        long long createReportCursor(
          in string accessKey,     // engine access key
          in long long jniReport   // jni report object handle
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Create group level cursor
        // @JSP support
        long long createGroupCursor(
          in string accessKey,     // engine access key
          in long long group       // group
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Create related group cursor
        // @JSP support
        long long createRelatedGroupCursor(
          in string accessKey,      // engine access key
          in long long group,       // group
          in long long parentCursor // parent cursor
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Create related group cursor for foreach tag
        // @JSP support
        long long createForeachGroupCursor(
          in string accessKey,      // engine access key
          in long long group,       // group
          in LongLongArray parentCursors // possible parent cursors
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Fetch next record given the cursor
        // @JSP support
        boolean fetchNext(
          in string accessKey,     // engine access key
          in long long source,     // source
          in long long cursor,     // cursor
          in boolean withInParent, //
          in long step
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get group object given group name in a report
        // @JSP support
        long long getGroup(
          in string accessKey,     // engine access key
          in long long jniReport,  // jni report object handle
          in wstring groupName     // group name
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get column value given column name
        // @JSP support
        long getColumnValue(
          in string accessKey,     // engine access key
          in long long source,     // source cursor
          in long long cursor,     // this cursor
          in wstring column,       // column name
          in wstring formatMask,   // formatmask
          out ByteArray value      // column value byte array
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get column string value given column name
        // @JSP support
        wstring getColumnValueString(
          in string accessKey,     // engine access key
          in long long source,     // source cursor
          in long long cursor,     // this cursor
          in wstring column,       // column name
          in wstring formatMask    // formatmask
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get column string value given column name
        // @JSP support
        StrArray getColumnValueStringWithTrigger(
          in string accessKey,     // engine access key
          in long long source,     // source cursor
          in long long cursor,     // this cursor
          in wstring column,       // column name
          in wstring formatMask,   // formatmask
          in wstring formatTrigger // format trigger
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get HTML string for named layout object
        // @JSP support
        ByteArray getLayoutHTML(
          in string accessKey,     // engine access key
          in wstring objName       // layout object name
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get array of properties of Long type
        // @JSP support
        LongLongArray getLongArrayProperty( // RAPI
          in string accessKey,     // engine access key
          in long long item,       // jni item
          in long property         // property id
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get array of properties of String type
        // @JSP support
        StrArray getStringArrayProperty( // RAPI
          in string accessKey,    // engine access key
          in long long item,      // jni item
          in long property        // property id
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set string property and return array of Long type
        // @JSP support
        LongLongArray setLongArrayProperty( // RAPI
          in string accessKey,    // engine access key
          in long long item,      // jni item
          in long property,       // property id
          in wstring attr         // string attr to set on the object
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set string property and return array of String type
        // @JSP support
        StrArray setStringArrayProperty( // RAPI
          in string accessKey,    // engine access key
          in long long item,      // jni item
          in long property,       // property id
          in wstring attr         // string attr to set on the object
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Generate GIF file for PFJ Graph, return HTML code
        // @JSP support
        // Bug2002616 Removed ImageURl argument
        string createPFJGraph(
          in string accessKey,    // engine access key
          in long long grpCursor, // group cursor
          in long long group,     // group
          in wstring id,          // id attribute
          in wstring graphGroup,  // graphGroup attribute
          in wstring graphSeries, // graphSeries attribute
          in wstring dataValue,   // dataValue attribute
          in wstring graphDef,    // graph XML definition
          in wstring hyperlink,   // graph hyperlink attribute
          in wstring altText,     // graph alternativeText attribute
          in long width,          // graph width
          in long height         // graph height
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // check which cursor the column is in
        // @JSP support
        long cursorWithColumn(
          in string accessKey,      // engine access key
          in wstring colName,       // column name
          in LongLongArray cursors  // possible parent cursors
        ) raises (RWException);

      };
    };

    module server
    {
      // Forward definition
      interface Connection; // Connection interface
      interface ServerComm; // server communication interface
      interface EngineComm; // engine communication interface

      ////////////////////////////////////////////////////////////////////////
      // Server interface, the methods client can call after bind
      ////////////////////////////////////////////////////////////////////////
      interface ServerClass
      {
        //////////////
        // Constants
        //////////////

        // user roles
        // These values have to be same as defined in rwwwvusr.sql
        const short ROLE_ADMINISTRATOR = 1;
        const short ROLE_DEVELOPER     = 2;
        const short ROLE_POWER_USER    = 3;
        const short ROLE_BASIC_USER    = 4;

        // server state constants
        const short STATE_INITIAL  = 0; // server is initializing itself
        const short STATE_READY    = 1; // server is ready to serve
        const short STATE_SHUTDOWN = 2; // server is shuting down itself

        // server shutdown mode
        const short DOWN_NORMAL    = 0; // clean up and shutdown normally
        const short DOWN_IMMEDIATE = 1; // shutdown immediately (through kill
                                        // mostly)  

        ////////////
        // Methods
        ////////////

        ///////////////////////////////////////////////////////////////////////
        // Methods for Client
        ///////////////////////////////////////////////////////////////////////
        ///////////////////////////////////////////////////////////////////////
        // Get server state, it returns one of STATE_ defined above
        short getState();

        ///////////////////////////////////////////////////////////////////////
        // Create a new Connection object from server, all operations to
        // the server has to go through Connection object
        Connection newConnection(
          in wstring clientId,      // client id
          in ByteArray clientSignature,// client signature
          in wstring username,      // username
          in wstring password,      // password, could be empty for web client
                                    // and we assume password has been verified
                                    // by SSO Login Server by client
          in wstring usertype,      // user type, same as jobtype, which
                                    // determine what security system to use
                                    // default null means report user
          out string connectionKey  // connection object access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Check whether server is secure or not
        boolean isSecure(
          in wstring usertype,      // user type, same as jobtype, which
                                    // determine what security system to use
                                    // default null means report user
          out string securityName   // security system name used by server
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Authenticate an user.
        // If failed to authenticate, the reason if in failReason
        // If it is system authentication, role also returned
        boolean authenticate(
          in wstring  username,    // username
          in wstring  password,    // password
          in wstring  usertype,    // user type, same as jobtype, which
                                   // determine what security system to use
                                   // default null means report user
          in StrArray propNames,   // additional property names
          in StrArray propValues,  // additional property values
          out short   role,        // the role the user is in (see const ROLE_*)
          out wstring failReason   // the reason of auth failure
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // register a server, called by other servers in the cluster
        // return server communication object that remote cluster server can
        // use from now on
        ServerComm registerServer(
          in wstring    rmtServerName,     // remote server name
          in ByteArray  rmtServerSignature,// remote server singnature
          in ServerComm rmtServerComm,     // remote server communication object
          inout string  serverKey          // serverComm access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // register a proxy server, called by proxy server launched by jasmine
        // server during startup
        void registerProxy(
          in wstring   clientId,        // client id
          in ByteArray clientSignature  // client signature
        ) raises (RWException);
      };

      /////////////////////////////////////////////////////////////////////////
      // Methods for engine communication
      /////////////////////////////////////////////////////////////////////////
      interface EngineComm
      {
        ///////////////////////////////////////////////////////////////////////
        // register a engine, called by engines
        string registerEngine(
          in string  accessKey,   // EngineComm access key for the EngineClass
          in wstring engineName,  // engine name in format of <engine_id>-<num>
          in engine::EngineClass engineObject // Engine object
        ) raises (RWException);   // access key to EngineComm object

        ///////////////////////////////////////////////////////////////////////
        // Ping this server to make sure the server is still alive
        void ping(
          in string accessKey      // server access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // update status for the job in the engine, called by engines
        void updateEngineJobStatus(
          in string accessKey,  // EngineComm access key
          in long jobId,        // job id
          in JobStatus status   // job status
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // update engine state, called by engines to its owner server
        void updateEngineState(
          in string  accessKey,  // EngineComm access key
          in wstring engineName, // engine name in format of <engine_id>-<num>
          in short   state       // engine state, see STATE_* above
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Add a destination for the given job (for distribution)
        long addDestination(
          in string   accessKey,   // EngineComm access key
          in long     jobId,       // id of the job this destination belongs to
          in wstring  destype,     // destination type (eg, "mail", "print",
                                   // "file", etc)
          in wstring  desname,     // desname (eg, printer name or mail list)
          in StrArray propNames,   // array of property names (eg, subject,
                                   // copies, etc.)
          in StrArray propValues   // corresponding property values
        ) raises (RWException);    // method returns destination id

        ///////////////////////////////////////////////////////////////////////
        // Set output for the job (filename & format)
        // This function can be called multiple times with different file names
        // for compound output
        void setJobOutput(
          in string   accessKey,  // EngineComm access key
          in long     jobId,      // job id
          in wstring  filename,   // main filename
          in short    format,     // file format
          in boolean  main,       // indicate whether it is main file of the
                                  // output
          in wstring  destkey,    // optional cache key for this destination
          in long     destId      // destination id returned from
                                  // addDestination()
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set output & content for the job (filename, format & content)
        // This method can be called multiple times with same filename, which
        // means to append the content into the same file. It also can be called
        // multiple times with different filename for compound output.
        void setJobOutputContent(
          in string    accessKey,  // EngineComm access key
          in long      jobId,      // job id
          in wstring   filename,   // file name
          in short     format,     // format of the content
          in boolean   main,       // indicate whether this is main file for
                                   // the job
          in wstring   destkey,    // optional cache key for this destination
          in long      destId,     // destination id returned from
                                   // addDestination()
          in ByteArray inBuffer    // input buffer contains content
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Share sub-job output for different destinations (eg. same pdf file
        // can be sent to mail and printer)
        void shareJobOutput(
          in string    accessKey,   // EngineComm access key
          in long      jobId,       // job id
          in long      destId,      // this destId will share the same output
          in long      masterDestId // stored for masterDestId
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Do distribution for all destinations that have been added into the
        // job
        void distribute(
          in string    accessKey,   // EngineComm access key
          in long      jobId        // job id
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get all destypes that server support
        // It returns an array of destype
        StrArray getDestypes(
          in string accessKey       // EngineComm access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get plugin parameter value by given name
        // It returns an array of destype
        wstring getPluginParam(
          in string  accessKey,      // EngineComm access key
          in wstring name            // parameter name
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get the Trace associated with the job, identified by the job
        // ID. Returns null if no object found.
        utility::Trace getJobTracer(
          in long     JobId       // Job ID for the current job
        );
      };

      /////////////////////////////////////////////////////////////////////////
      // Server communication interface used by other servers in cluster
      /////////////////////////////////////////////////////////////////////////
      interface ServerComm
      {
        ///////////////////////////////////////////////////////////////////////
        // Create a new Connection object from server, all operations to
        // the server has to go through Connection object
        Connection newConnection(
          in string accessKey,      // server access key
          in wstring username,      // username
          in wstring password,      // password
          in wstring usertype,      // user type, same as jobtype, which
                                    // determine what security system to use
                                    // default null means report user
          out string connectionKey  // connection object access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Find a duplicated job in current or past job queue in this server
        // for calling server, called by other servers in the cluster
        // Return duplicated job id, if the value is not zero. Otherwise
        // no duplicated job is found
        long findDuplicatedJob(
          in string  accessKey,      // server access key
          in wstring cmdline         // command line for the job
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get an idle engine for remote server
        // called by other servers in the cluster
        // If it returns null, no idle engine available on this server.
        // Otherwise, the engine is reserved and ready to use.
        wstring getIdleEngine(
          in string  accessKey,   // server access key
          in wstring jobType      // job type
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Run the job on the called server using specified engineName,
        // called by other servers in the cluster.
        // Reset the timeQueued parameter in the job object because the
        // original enqueue time is earlier than transfering time
        void runJob(
          in string    accessKey,  // server access key
          in long      jobId,      // the job id created by newJob() on
                                   // connection object
          in long long timeQueued, // original enqueue time
          in wstring   engineName  // engine name that is reserved for the job
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Run sycn job in current job queue of this server if there is one
        // waiting to run. Used by other server in the cluster to trigger
        // waiting jobs to compete for idle engine in the cluster
        // Return true - found such job,
        //        false - no job is waiting to run in this server
        boolean runCurrentSyncJob(
          in string  accessKey,     // server access key
          in wstring engineName     // available engine name
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Ping this server to make sure the server is still alive
        void ping(
          in string accessKey      // server access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Tell this server that the specified server is going down,
        // called by other servers in the cluster
        void serverDown(
          in string  accessKey,    // server access key
          in wstring serverName    // the name of the server that is going down
        ) raises (RWException);
      };

      /////////////////////////////////////////////////////////////////////////
      // Connection object a client can operate on
      /////////////////////////////////////////////////////////////////////////
      interface Connection
      {
        // object types
        const short TYPE_MESSAGE            = 1;
        const short TYPE_CURRENT_CONNECTION = 2;
        const short TYPE_NEW_CONNECTION     = 3;
        const short TYPE_NEW_SERVER         = 4;

        /////////////////////////////////
        // Methods for Server operation
        /////////////////////////////////

        ///////////////////////////////////////////////////////////////////////
        // Check accessability of a web command
        // If failed, it throws RWException, and the reason of failure is in
        // the exception
        void webCommandCheck(
          in string  accessKey, // connection object access key
          in wstring webCommand // web command to be checked
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Check whether current user is admin or not admin user
        // for non-secure user, compare with admin user stashed in server
        // (note, first logon user is admin user for the non-secure server)
        // for secure user, the user privilege comes from webdb
        boolean isAdmin(
          in string accessKey  // connection object access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Change admin user password
        void changeAdminPassword(
          in string  accessKey,    // connection object access key
          in wstring oldPassword,  // old password
          in wstring newPassword   // new password
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Empty server cache, only available for admin user
        void emptyCache(
          in string accessKey     // connection object access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Shut down the reports server
        oneway void shutdownServer(
          in string accessKey,    // connection object access key
          in long shutdownMode    // shutdownMode: DOWN_IMMEDIATE & DOWN_NORMAL
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set server property
        void setServerProperty(
          in string  accessKey,    // connection object access key
          in long    propertyId,   // property id
          in wstring value         // property value
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get server property
        wstring getServerProperty(
          in string accessKey,    // connection object access key
          in long   propertyId    // property id
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set server properties at once
        void setServerProperties(
          in string accessKey,     // connection object access key
          in LongArray propertyIds,// array of property id
          in StrArray values       // array of property value
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get server properties at once
        StrArray getServerProperties(
          in string accessKey,     // connection object access key
          in LongArray propertyIds // array of property id
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get engine environment
        void getEngineEnvs(
          in string accessKey,     // connection object access key
          in string jobType,       // the job type that dictates which engine 
          out StrArray envNames,   // environment names
          out StrArray envValues   // environment values
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get server information that is returned in xml format
        wstring getServerInfo(
          in string accessKey      // connection object access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Disconnect client from Connection object, and server will
        // destroy the Connection object
        oneway void disconnect(
          in string accessKey      // connection object access key
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get Queue Information
        QueueInfo getQueueInfo(
          in string  accessKey,   // connection object access key
          in long    cutOffDays,  // cut off days if infoBitMask has
                                  // QUEUE_INFO_PASTJOBS_DAYS
          in long    maxRetNum,   // maximum number of jobs to return
                                  // -1 means no limit.
          in long    startCounter,// starting counter of job to return
          inout long infoBitMask, // bit mask to indicate what info to retrive
                                  // and what actually returned
          out long   totalNum,    // total number of jobs in the queue(s)
          out long long lastUpdate// when last update happens in the queue(s)
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get an idle engine
        // return name of engine reserved and ready to use
        wstring getIdleEngine(
          in string accessKey,              // server access key,
          in long   jobId,                  // the job which wants to get engine
          out engine::EngineClass engineHolder,  // hold engine object if found
          out string engineKeyHolder        // hold engine key if found
        ) raises (RWException);

        ////////////////////
        // Methods for Job
        ////////////////////

        ///////////////////////////////////////////////////////////////////////
        // Create a new job for the command line
        long newJob(
          in string  accessKey,  // connection object access key
          in wstring cmdline     // command line
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Create a new job for the command which is in xml format
        long newXMLJob(
          in string  accessKey,  // connection object access key
          in wstring xml         // xml content
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set (send) report definition file (rdf, xml, or any dependent file)
        // for the specified into the server. Client could call this method
        // multiple times to set multiple files
        void setJobFile(
          in string    accessKey,  // engine access key
          in long      jobId,      // the job id the file is associated with
          in wstring   fileName,   // file name
          in wstring   fileFormat, // file format, such as "xml"
          in ByteArray fileStream, // content of the file
          in boolean   main        // indicate whether the file is main
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Run job
        // return if successfully submitted job for asynchronous job
        //        or if successfully run for synchronous job
        // throw exception if submission failed for asynchronous job
        //                 or if running a reports failed for synchronous job
        // If objTypeHld returns TYPE_MESSAGE
        //    numHld returns message id, either SUCC_RUN (sync job) or
        //           SUCC_SUBMIT (async job)
        //    strHld returns message string
        // If objTypeHld returns TYPE_CURRENT_CONNECTION
        //    get output from current connection object
        // If objTypeHld returns TYPE_NEW_CONNECTION
        //    means it found duplicated job in another cluster server, and
        //    client can use returned new connection object to get output.
        //    objHld returns new connection object in another server
        //    jobIdHld returns new job id in new server
        //    nameHld returns new server name
        //    stringHld returns new connection object access key
        // If objTypeHld returns TYPE_NEW_SERVER
        //    means this server can't run the job (maybe because it is shuting
        //    down itself), so it recommends client to try the new server.
        //    objHld returns new server object
        //    nameHld returns new server name
        void runJob(
          in string   accessKey,  // connection object access key
          in long     jobId,      // job id
          out short   objTypeHld, // return object type
          out Object  objHld,     // the object from which to get output
          out long    jobIdHld,   // hold job id for newly created job
          out wstring nameHld,    // name of server the job is assigned
          out long    numHld,     // message id
          out wstring strHld      // object access key or message string
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Reschedule or resubmit the job asynchronously
        // if newSchedule is null, it resubmit the job.
        void reScheduleJob(
          in string  accessKey,    // connection object access key
          in long    jobId,        // the original job id
          in wstring newSchedule   // new schedule string, if it is null,
                                   // resubmit the job
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Reorder job in the current job queue.
        void reOrderJob(
          in string accessKey,    // connection object access key
          in long jobId,          // the job to be moved
          in long offset          // the offset the job is going to move
                                  // positive value: move towards the top
                                  // negative value: move towards the bottom
                                  // use big positive value to move to top
                                  // use big negative value to move to bottom
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Cancel currently running job or scheduled job and put it
        // into passed job queue
        void cancelJob(
          in string accessKey,    // connection object access key
          in long jobId           // job to be cancelled
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Kill the engine that runs the job
        void killJobEngine(
          in string accessKey,    // connection object access key
          in long jobId           // the job id the engine is running on
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // get job info including status
        JobInfo getJobInfo(
          in string accessKey,    // connection object access key
          in long jobId,          // job id,
          out long index          // index in the queue, 
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get main output file name (function return), format and size
        wstring getMainFile(
          in string accessKey,      // connection access key
          in long jobId,            // job id
          out short format,         // file format
          out long long size        // file size
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get additional output file names (function return), formats and sizes
        StrArray getAdditionalFiles(
          in string accessKey,      // connection access key
          in long jobId,            // job id
          out ShortArray formats,   // formats for additional files
          out LongLongArray sizes   // sizes for additional files
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get job output size including main file and additional files
        long long getJobOutputSize(
          in string accessKey,      // connection access key
          in long jobId             // job id
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get main or additional output file stream
        // return: true - more to come
        //         false - end of file has been reached
        boolean getFileStream(
          in string accessKey,      // connection access key
          in long jobId,            // job id
          in wstring filename,      // file name
          out ByteArray outStream   // output stream
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Get the Trace associated with the job, identified by the job
        // ID. Returns null if no object found.
        utility::Trace getJobTracer(
          in long     JobId     // Job id for the current job
        );

        ///////////////////////////////////////////////////////////////////////
        // Methods for cache
        ///////////////////////////////////////////////////////////////////////

        ///////////////////////////////////////////////////////////////////////
        // Create a new cache job to check and retrieve duplicated cache output
        // return: true - found duplicated cache
        //                case 1: connHolder holds null - use current connection
        //                case 2: connHolder holds new Connection value and
        //                        keyHolder holds new key string - the cache
        //                        is found in another cluster server and the
        //                        name of the server is in nameHolder
        //                in both cases, use getMainFile(), getAdditionalFiles()
        //                and getFileStream() to retrieve the content from cache
        //         false - not found duplicated cache, client can call
        //                 setCacheContent() to set cache content for the job 
        boolean cacheJob(
          in string  accessKey,     // connection access key
          in wstring commandLine,   // command line, eg. module=foo.jsp
                                    // cachekey="abc" tolerance=10 expiration=10
          out Connection connHolder,// from which client can get cache output
          out long    jobIdHolder,   // holds newly created job id
          out wstring nameHolder,    // name of server the job is assigned
          out string  keyHolder      // the access key for the connection object
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set main or additional file content into cache
        // This method can be called multiple times with same subitemId, which
        // means to append the content
        void setCacheContent(
          in string  accessKey,      // connection access key
          in long    jobId,          // job id
          in wstring filename,       // filename
          in short   format,         // format of the content
          in ByteArray inBuffer      // input buffer contains content
        ) raises (RWException);

        ///////////////////////////////////////////////////////////////////////
        // Set the cache job ready and move the job from current job queue
        // to past job queue
        void setCacheJobReady(
          in string accessKey,      // connection access key
          in long   jobId           // job id
        ) raises (RWException);
      };
    };
  };
};