tdesdk/cervisia/cvsservice/DESIGN

OVERVIEW
--------

The cvs DCOP service consists of the following three parts:

1. CvsService - The main interface to the functionality of the cvs command line
                client. There is one method for each cvs command, e.g. add,
                checkout, commit, etc... The methods assemble the command line
                arguments, create a CvsJob and return a DCOPRef object for it
                to the caller. There is one instance of this service for each
                application instance.

2. Repository - This DCOPObject manages the configuration data of the current
                cvs repository. The data is automatically updated when other
                service instances change it.

3. CvsJob     - This class represents a cvs job. You can execute and cancel it,
                and you can retrieve the output of the cvs client by either
                connecting to the proper DCOP Q_SIGNALS or by using the output()
                method. There are two types of jobs. First the non-concurrent
                job which has to run alone, like cvs update or import. Second
                the jobs which can run concurrently like cvs log or annotate.

USAGE
-----

How-to use this service in C++ applications:

    // start DCOP service
    QString error;
    QCString appId;

    KApplication::startServiceByDesktopName("cvsservice", QStringList(), &error,
                                            &appId);

    // create stub for repository
    Repository_stub repository(appId, "CvsRepository");

    // set directory of working copy
    repository.setWorkingCopy("/home/user/kde/kdesdk/cervisia");

    // create stub for service
    CvsService_stub cvsService(appId, "CvsService");

    // call "cvs log" for cervisiapart.h
    DCOPRef job = cvsService.log("cervisiapart.h");

    // connect to Q_SIGNALS to get output
    connectDCOPSignal(job.app(), job.obj(), "jobExited(bool, int)", [MY SLOT]);
    connectDCOPSignal(job.app(), job.obj(), "receivedStdout(QString)",
                      [MY SLOT]);

    // execute the cvs command
    job.execute();


How-to use this service in a shell script:

    #!/bin/sh

    # start DCOP service
    APP=`dcopstart cvsservice`

    # set directory of working copy
    dcop $APP CvsRepository setWorkingCopy /home/user/kde/kdesdk/cervisia

    # call "cvs log" for cervisiapart.h
    JOB=`dcop $APP CvsService log cervisiapart.h`

    # execute the cvs command
    dcop $JOB execute

    # print the output on stdout
    dcop $JOB output

    # stop DCOP service
    dcop $APP CvsService quit


How-to use this service in a javascript:

    #!/usr/bin/env kjscmd

    var client = new DCOPClient(this);
    if ( client.attach() )
    {
        // start DCOP service
        var appID = client.dcopStart("cvsservice");

        // set directory of working copy
        client.send(appID, "CvsRepository", "setWorkingCopy(QString)", "/home/user/kde/kdesdk/cervisia");

        // call "cvs log" for cervisiapart.h
        var job = client.call(appID, "CvsService", "log(QString)", "cervisiapart.h");

        // execute the cvs command
        job.call("execute()");

        // wait for job to finish
        while( job.call("isRunning()") );

        // print the output on stdout
        var output = job.call("output()");
        println(output);

        // stop DCOP service
        client.send(appID, "CvsService", "quit()");
    }