vcs/dvcs/dvcsjob.h

   1 /***************************************************************************
   2  *   This file was partly taken from KDevelop's cvs plugin                 *
   3  *   Copyright 2002-2003 Christian Loose <christian.loose@hamburg.de>      *
   4  *   Copyright 2007 Robert Gruber <rgruber@users.sourceforge.net>          *
   5  *                                                                         *
   6  *   Adapted for DVCS                                                      *
   7  *   Copyright 2008 Evgeniy Ivanov <powerfox@kde.ru>                       *
   8  *                                                                         *
   9  *   This program is free software; you can redistribute it and/or         *
  10  *   modify it under the terms of the GNU General Public License as        *
  11  *   published by the Free Software Foundation; either version 2 of        *
  12  *   the License or (at your option) version 3 or any later version        *
  13  *   accepted by the membership of KDE e.V. (or its successor approved     *
  14  *   by the membership of KDE e.V.), which shall act as a proxy            *
  15  *   defined in Section 14 of version 3 of the license.                    *
  16  *                                                                         *
  17  *   This program is distributed in the hope that it will be useful,       *
  18  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  19  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  20  *   GNU General Public License for more details.                          *
  21  *                                                                         *
  22  *   You should have received a copy of the GNU General Public License     *
  23  *   along with this program.  If not, see <http://www.gnu.org/licenses/>. *
  24  ***************************************************************************/
  25
  26
  27 #ifndef DVCS_JOB_H
  28 #define DVCS_JOB_H
  29
  30 #include <QtCore/QStringList>
  31 #include <QtCore/QVariant>
  32 #include <KDE/KProcess>
  33
  34 #include "../vcsexport.h"
  35 #include "../vcsjob.h"
  36
  37 class DVCSjobPrivate;
  38
  39 /**
  40  * This class is capable of running our dvcs commands.
  41  * Most of all DVCSjobs are created in DVCS executors, but executed in DistributedVersionControlPlugin or
  42  * any managers like BranchManager.
  43  * @note Connect to Kjob::result(KJob*) to be notified when the job finished.
  44  *
  45  * How to create DVCSjob:
  46  * @code
  47  * DVCSjob* job = new DVCSjob(vcsplugin);
  48  * if (job)
  49  * {
  50  *     job->setDirectory(workDir);
  51  *     *job << "git-rev-parse";
  52  *     foreach(const QString &arg, args) // *job << args can be used instead!
  53  *     *job << arg;
  54  *     return job;
  55  * }
  56  * if (job) delete job;
  57  * return NULL;
  58  * @endcode
  59  *
  60  * Usage example 1:
  61  * @code
  62  * VcsJob* j = add(DistributedVersionControlPlugin::d->m_ctxUrlList, IBasicVersionControl::Recursive);
  63  * DVCSjob* job = dynamic_cast<DVCSjob*>(j);
  64  * if (job) {
  65  *     connect(job, SIGNAL(result(KJob*) ),
  66  *             this, SIGNAL(jobFinished(KJob*) ));
  67  *     job->start();
  68  * }
  69  * @endcode
  70  *
  71  * Usage example 2:
  72  * @code
  73  * DVCSjob *branchJob = d->branch(repo, baseBranch, newBranch);
  74  * DVCSjob* job = gitRevParse(dirPath.path(), QStringList(QString("--is-inside-work-tree")));
  75  * if (job)
  76  * {
  77  *     job->exec();
  78  *     if (job->status() == KDevelop::VcsJob::JobSucceeded)
  79  *         return true;
  80  *     else
  81  *     //something, mabe even just
  82  *         return false
  83  * }
  84  * @endcode
  85  *
  86  * @author Robert Gruber <rgruber@users.sourceforge.net>
  87  * @author Evgeniy Ivanov <powerfox@kde.ru>
  88  */
  89 class KDEVPLATFORMVCS_EXPORT DVCSjob : public KDevelop::VcsJob
  90 {
  91     Q_OBJECT
  92 public:
  93     DVCSjob(KDevelop::IPlugin* parent);
  94     virtual ~DVCSjob();
  95
  96     /**
  97      * Call this method to clear the job (for example, before setting another job).
  98      */
  99     void clear();
 100
 101     /**
 102      * It's not used in any DVCS plugin.
 103      */
 104     void setServer(const QString& server);
 105
 106     /**
 107      * Sets working directory.
 108      * @param directory Should contain only absolute path. Relative path or "" (working dir) are depricated and will make job failed.
 109      * @note In DVCS plugins directory variable is used to get relative pathes.
 110      */
 111     void setDirectory(const QString& directory);
 112
 113     /**
 114      * Sets standart Input file.
 115      */
 116     void setStandardInputFile(const QString &fileName);
 117
 118     /**
 119      * Returns current working directory.
 120      */
 121     QString getDirectory();
 122
 123     /**
 124      * Call this method to set command to execute and its arguments.
 125      * @note Don't forget <<"one two"; is not the same as <<"one"<<"two"; Use one word(command, arg) per one QString!
 126      */
 127     DVCSjob& operator<<(const QString& arg);
 128
 129     /**
 130      * Overloaded convinience function.
 131      * @see operator<<(const QString& arg).
 132      */
 133     DVCSjob& operator<<(const char* arg);
 134
 135     /**
 136      * Overloaded convinience function.
 137      * @see operator<<(const QString& arg).
 138      */
 139     DVCSjob& operator<<(const QStringList& args);
 140
 141     /**
 142      * Call this mehod to start this job.
 143      * @note Default communiaction mode is KProcess::AllOutput.
 144      * @see Use setCommunicationMode() to override the default communication mode.
 145      */
 146     virtual void start();
 147
 148     /**
 149      * In some cases it's needed to specify the communisation mode between the
 150      * process and the job object. This is for instance done for the "git status"
 151      * command. If stdout and stderr are processed as separate streams their signals
 152      * do not always get emmited in correct order by KProcess. Which will lead to a
 153      * screwed up output.
 154      * @note Default communiaction mode is KProcess::SeparateChannels.
 155      */
 156     void setCommunicationMode(KProcess::OutputChannelMode comm);
 157
 158     /**
 159      * @return The command that is executed when calling start().
 160      */
 161     QString dvcsCommand() const;
 162
 163     /**
 164      * @return The whole output of the job.
 165      */
 166     QString output() const;
 167
 168     // Begin:  KDevelop::VcsJob
 169
 170     /**
 171      * Sets executions reults.
 172      * In most cases this method is used by IDVCSexecutor
 173      * @see fetchResults()
 174      */
 175     virtual void setResults(const QVariant &res);
 176
 177     /**
 178      * Returns execution results stored in QVariant.
 179      * Mostly used in vcscommitdialog.
 180      * @see setResults(const QVariant &res)
 181      */
 182     virtual QVariant fetchResults();
 183
 184     /**
 185      * Sets exit status (d->failed variable).
 186      * Since only executors can parse the job to set result, they can connect parsers to readyForParsing(DVCSjob) using
 187      * Qt::DirectConnection to set the result. For example git-status can return exit status 1
 188      * if you don't set exit status in your parser then you will have JobFailes in status() result.
 189      * @note First result is set in slotProcessExited() or slotProcessError().
 190      */
 191     virtual void setExitStatus(const bool exitStatus);
 192
 193     /**
 194      * Returns JobStatus
 195      * @see KDevelop::VcsJob::JobStatus
 196      */
 197     virtual KDevelop::VcsJob::JobStatus status() const;
 198
 199     /**
 200      * Returns pointer to IPlugin (which was used to create a job).
 201      */
 202     virtual KDevelop::IPlugin* vcsPlugin() const;
 203     // End:  KDevelop::VcsJob
 204
 205     KProcess *getChildproc();
 206
 207 public Q_SLOTS:
 208     /**
 209      * Cancel slot.
 210      */
 211     void cancel();
 212
 213     /**
 214      * Returns if the job is running.
 215      */
 216     bool isRunning() const;
 217
 218 signals:
 219     void readyForParsing(DVCSjob *job);
 220
 221 private Q_SLOTS:
 222     void slotProcessError( QProcess::ProcessError );
 223     void slotProcessExited(int exitCode, QProcess::ExitStatus exitStatus);
 224     void slotReceivedStdout(const QStringList&);
 225     void slotReceivedStderr(const QStringList&);
 226
 227 private:
 228     void jobIsReady();
 229     DVCSjobPrivate* const d;
 230     QVariant results;
 231 };
 232
 233 #endif