View source for MoleQueue JSON-RPC Implementation

= This page is out-of-date =

The mechanism for handling JSON-RPC transmissions has been simplified. This page will be rewritten at some point.

== Language, backends ==

The MoleQueue JSON-RPC implemention is written in C++, using the [http://jsoncpp.sourceforge.net/ JsonCpp] parsers. It exposes a [http://qt.nokia.com Qt 4] interface that provides interprocess communication through a local socket with a visible Qt signal/slot interface.

== Components ==

The implementation consists of the following classes:

=== MoleQueue::JsonRpc ===

Internal class used to generate and handle JSON-RPC requests, responses, and notifications as described in the [[MoleQueue JSON-RPC Specification]].

Methods:
* <tt>static QByteArray generateJobRequest(const JobRequest &req, unsigned long requestId)</tt>: Process a JobRequest into a MoleQueue JSON-RPC QByteArray, ready to send to a QLocalSocket.
* <tt>static QByteArray generateJobCancellation(const JobRequest &req, unsigned long requestId)</tt>Process a request to cancel a JobRequest into a MoleQueue JSON-RPC QByteArray.
* <tt>static QByteArray generateQueueList(const QueueManager *, unsigned long requestId)</tt>: Generate a MoleQueue JSON-RPC QByteArray of the available queues/programs.
* <tt>QVector<unsigned long> interpretIncoming(const QByteArray &)</tt>: Interpret an incoming MoleQueue JSON-RPC packet, identify the type (should be a request), and emit an appropriate signal. Return value is a unique identifier for this packet that can be used later to match the signal to this packet (should be the JSON-RPC packet id). A QVector is used to handle batch requests.
* <tt>static QByteArray generateJobStateChangeNotification(unsigned long moleQueueId, JobState oldState, JobState newState)</tt>
* <tt>static bool validateRequest(const QString &)</tt>
* <tt>static bool validateResponse(const QString &)</tt>
* <tt>static bool validateNotification(const QString &)</tt>

Signals:
* <tt>void queueListRequestReceived(unsigned long packetHandle)</tt>
* <tt>void queueListReceived(unsigned long packetHandle, const QList<QPair<QString, QStringList> > &)</tt>
* <tt>void jobSubmissionRequestReceived(unsigned long packetHandle, const QHash<QString, QVariant> &options)</tt>
* <tt>void successfulSubmissionReceived(unsigned long packetHandle, unsigned long moleQueueId, unsigned long jobId, const QDir &workingDir)</tt>
* <tt>void failedSubmissionReceived(unsigned long packetHandle, unsigned long moleQueueId, unsigned long jobId, const QDir &workingDir)</tt>
* <tt>void jobCancellationRequestReceived(unsigned long packetHandle, unsigned long moleQueueId)</tt>
* <tt>void jobCancellationConfirmationReceived(unsigned long packetHandle, unsigned long moleQueueId)</tt>
* <tt>void jobStateChangeReceived(unsigned long packetHandle, unsigned long moleQueueId, JobState oldState, JobState newState)</tt>

=== MoleQueue::MoleQueueClient ===

Client interface providing methods for requesting and monitoring calculations. This class generates and manages <tt>JobRequest</tt> objects, which are state objects that define a single job's configuration.

Methods:
* <tt>JobRequest & newJobRequest()</tt>: Creates and registers a new JobRequest object with this client.
* <tt>bool submitJobRequest(JobRequest &)</tt>: Submit a JobRequest to the MoleQueue server.
* <tt>bool cancelJobRequest(JobRequest &)</tt>: Cancel a JobRequest that has been submitted to the MoleQueue server.

=== MoleQueue::JobRequest ===

Class describing a single job from the client's side.

Methods:
* <tt>MoleQueueClient & client()</tt>: Return the parent MoleQueueClient.
* <tt>unsigned long id() const</tt>: Unique identifier for this job request.
* <tt>unsigned long jobId() const</tt>: If set, a queue specific job identifier.
* Various setters/getters for file path, job options, etc.

Slots:
* <tt>bool submit()</tt>: Equivalent to <tt>this->client.submitJobRequest(this)</tt>.
* <tt>bool cancel()</tt>: Equivalent to <tt>this->client.cancelJobRequest(this)</tt>.
* <tt>bool destroy()</tt>: Removes a JobRequest from the client. Otherwise the instance will persist for the lifetime of the MoleQueueClient.

Signals:
* <tt>void stateChanged(JobState oldState, JobState newState)</tt>: Emitted when the server indicates a change in the job's status.
* <tt>void submitted()</tt>: Emitted when the job is successfully submitted to the MoleQueueServer.
* <tt>void error(ErrorCode ec, const QString &err)</tt> Emitted if an error is encountered.
* <tt>void finished()</tt>: Emitted when the job execution terminates.

ErrorCode values:
* <tt>SUBMISSION_ERROR</tt>: Error submitting request to MoleQueueServer.

=== MoleQueue::MoleQueueServer ===

Server for handling requests from and sending notifications to MoleQueueClient instances. It holds a pointer to a QueueManager and directly sends requests to the appropriate Queue objects.

Methods:
* <tt>setQueueManager(QueueManager *)</tt>: Sets the QueueManager.
* <tt>QueueManager * queueManager()</tt>: Get the current QueueManager instance.