plugin_utils.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: plugin_utils.hpp,v $
 * PRODUCTION Revision 1000.4  2004/04/12 18:12:51  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.44
 * PRODUCTION
 * ===========================================================================
 */

#ifndef GUI_CORE___PLUGIN_UTILS__HPP
#define GUI_CORE___PLUGIN_UTILS__HPP

/*  $Id: plugin_utils.hpp,v 1000.4 2004/04/12 18:12:51 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Authors:  Mike DiCuccio
 *
 * File Description:
 *    CPluginUtils -- utilities for managing the interface between the plugin
 *                    architecture and the GBENCH framework
 */

#include <gui/core/selection_buffer.hpp>
#include <gui/core/obj_convert.hpp>
#include <gui/utils/reporter.hpp>

#include <gui/plugin/PluginValue.hpp>
#include <gui/plugin/AlgoCommand.hpp>
#include <gui/plugin/DataCommand.hpp>
#include <gui/plugin/ViewCommand.hpp>

#include <serial/iterator.hpp>

BEGIN_NCBI_SCOPE

BEGIN_SCOPE(objects)
    class CPluginArg;
    class CPluginArgSet;
    class CPluginCommand;
    class CPluginInfo;
    class CPluginMessage;
    class CPluginReply;
    class CPluginRequest;
    class CScope;
    class CSeq_align;
    class CSeq_annot;
    class CSeq_entry;
    class CSeq_feat;
    class CSeq_loc;
END_SCOPE(objects)

class CPluginHandle;
class CPluginRegistry;
class CConvertCache;

//
// class CPluginUtils is a place-holder class for static functions that
// facilitate using the plugin architecture.
//
class NCBI_GUICORE_EXPORT CPluginUtils
{
public:
    // generic argument list typedef
    typedef list< CRef<objects::CPluginArg> > TArgs;

    // typedef for ordered pairs of selectied items.  These are explicitly
    // pairs because we in general need a scoe (document) to travel with the
    // data model object
    typedef pair< CConstRef<CObject>, CConstRef<IDocument> > TSelection;


    // Fit a set of objects into a set of plugin arguments.  This version
    // takes as its input a set of selections from a selection buffer.
    static int FillArgs(objects::CPluginArgSet&    args,
                        const TConstScopedObjects& selections);

    // Fit a set of objects into a set of plugin arguments.  This version
    // takes as its input a set of CPluginValues.  Only the object
    // values will be processed.
    static int FillArgs(objects::CPluginArgSet&           args,
                        const objects::CPluginArg::TData::TArray& objects);

    // Fit a set of objects into a set of plugin arguments.  This version
    // takes as its input a document.
    static int FillArgs(objects::CPluginArgSet& args,
                        const IDocument& doc);

    // this function performs a similar task to FillArgs(); however, instead of
    // actually filling the set of arguments automatically, it returns true if
    // any of the selections indicated *can* fit.  The primary use of this is
    // to determine if a set of plugins could accept some of the selections
    static bool CanFitArgs(const objects::CPluginArgSet& args,
                           const IDocument& doc,
                           CConvertCache* cache = NULL);

    static bool CanFitArgs(const objects::CPluginArgSet& args,
                           const CSelectionBuffer& buf,
                           CConvertCache* cache = NULL);

    static bool CanFitArgs(const objects::CPluginArgSet& args,
                           const TConstScopedObjects& selections,
                           CConvertCache* cache = NULL);

    //
    // plugin dispatching
    //

    enum EDispatchWhen {
        eDispatch_Now,
        eDispatch_Deferred
    };

    // call a plugin by name, passing in a selection buffer.  This version
    // responds to algorithm commands.
    static void CallPlugin(const string& plugin_name,
                           objects::EAlgoCommand cmd,
                           const CSelectionBuffer& selections,
                           IReporter*       reporter = NULL,
                           const string&    ctx_name = "",
                           EDispatchWhen    when = eDispatch_Deferred);

    // call a plugin by name, passing in a selection buffer.  This version
    // responds to view commands.
    static void CallPlugin(const string& plugin_name,
                           objects::EDataCommand cmd,
                           const CSelectionBuffer& selections,
                           IReporter*       reporter = NULL,
                           const string&    ctx_name = "",
                           EDispatchWhen    when = eDispatch_Deferred);

    // call a plugin by name, passing in a selection buffer.  This version
    // responds to data commands.
    static void CallPlugin(const string& plugin_name,
                           objects::EViewCommand cmd,
                           const CSelectionBuffer& selections,
                           IReporter*       reporter = NULL,
                           const string&    ctx_name = "",
                           EDispatchWhen    when = eDispatch_Deferred);

    // call a plugin by name, passing in a document.  This version
    // responds to algorithm commands.
    static void CallPlugin(const string& plugin_name,
                           objects::EAlgoCommand cmd,
                           const IDocument* doc = NULL,
                           IReporter*       reporter = NULL,
                           const string&    ctx_name = "",
                           EDispatchWhen    when = eDispatch_Deferred);

    // call a plugin by name, passing in a document.  This version
    // responds to view commands.
    static void CallPlugin(const string& plugin_name,
                           objects::EDataCommand cmd,
                           const IDocument* doc = NULL,
                           IReporter*       reporter = NULL,
                           const string&    ctx_name = "",
                           EDispatchWhen    when = eDispatch_Deferred);

    // call a plugin by name, passing in a document.  This version
    // responds to data commands.
    static void CallPlugin(const string& plugin_name,
                           objects::EViewCommand cmd,
                           const IDocument* doc = NULL,
                           IReporter*       reporter = NULL,
                           const string&    ctx_name = "",
                           EDispatchWhen    when = eDispatch_Deferred);

    // command through which all the CallPlugin(...) commands filter
    static void CallPlugin(objects::CPluginMessage& msg,
                           const TConstScopedObjects& selections,
                           EDispatchWhen when = eDispatch_Deferred);

    // call a plugin by name, passing in a fully qualified message object.
    // This is the final recipient of all CallPlugin() commands, and will
    // process the request non-interactively
    static void CallPlugin(objects::CPluginMessage& msg,
                           EDispatchWhen when = eDispatch_Deferred);

    //
    // argument validation functions
    //

    // validate an entire set of arguments
    static bool IsValid(const objects::CPluginArgSet& args);

    // validate a given argument.  This insures that the argument contains
    // a valid value, and that this value meets the argument's constraints.
    static bool IsValid(const objects::CPluginArg& arg);

    // validate a single plugin value
    static bool IsValid(const objects::CPluginValue& value);

    // check the constraints on a given argument
    static bool CheckConstraints(const objects::CPluginArg& arg,
                                 CConvertCache* cache = NULL);

    // individual constraint checking function.  This is used by
    // CheckConstraints() as well as by CanFitArgs(), and its API
    // is a bit odd as a result.
    static bool CheckConstraints(const objects::CPluginArg& arg,
                                 objects::CScope& scope, const CObject& obj,
                                 CConvertCache* cache = NULL);

    //
    // object conversion functions
    //

    // convert an argument to a named container of items
    static vector<string> ArgToStringVec(const objects::CPluginArg& arg);

    // retrieve the plugin info object for a named plugin.
    // this will throw if the plugin isn't found.
    static const objects::CPluginInfo& GetInfo(const string& plugin_name);

    // return a string describing an arbitrary object.  This is a single
    // entry-point function that will determine the best possible label to use.
    static string GetLabel(const CObject& obj, objects::CScope* scope);

private:

    static objects::CPluginCommand*
    x_GetCommand(objects::CPluginRequest& request);

};


//
// typedefs to make standard plugin args easier to deal with
//
BEGIN_SCOPE(plugin_args)

    typedef list< pair< CConstRef<IDocument>,
                        CConstRef<objects::CSeq_id> > >      TIdList;
    typedef list< pair< CConstRef<IDocument>,
                        CConstRef<objects::CSeq_feat> > >    TFeatList;
    typedef list< pair< CConstRef<IDocument>,
                        CConstRef<objects::CSeq_loc> > >     TLocList;
    typedef list< pair< CConstRef<IDocument>,
                        CConstRef<objects::CSeq_entry> > >   TEntryList;
    typedef list< pair< CConstRef<IDocument>,
                        CConstRef<objects::CSeq_align> > >   TAlignList;
    typedef list< pair< CConstRef<IDocument>,
                        CConstRef<objects::CSeq_annot> > >   TAnnotList;
    typedef list< pair< CConstRef<IDocument>,
                        CConstRef<objects::CBioseq> > >      TBioseqList;

END_SCOPE(plugin_args)