[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-commits
Subject: [nepomuk-web-extractor] dev-scripts/newplugin: Provide more
From: Artem Serebriyskiy <v.for.vandal () gmail ! com>
Date: 2011-07-19 7:22:17
Message-ID: 20110719072217.B8E7AA60A6 () git ! kde ! org
[Download RAW message or body]
Git commit 098874969129cef0fe31c00a6ef80ed7d23f8163 by Artem Serebriyskiy.
Committed on 19/07/2011 at 09:20.
Pushed by artemserebriyskiy into branch 'master'.
Provide more documentation in supplilde templates for plugin
1. Templates that are used to easy plugin creation now has some docs
embeded into them. These docs will apear in resulting code too.
M +14 -0 dev-scripts/newplugin/plugin.cpp.template
M +3 -0 dev-scripts/newplugin/plugin.h.template
M +32 -1 dev-scripts/newplugin/executive.cpp.template
M +6 -0 dev-scripts/newplugin/executivereply.cpp.template
M +3 -1 dev-scripts/newplugin/executive.h.template
M +15 -2 dev-scripts/newplugin/executivereply.h.template
http://commits.kde.org/nepomuk-web-extractor/098874969129cef0fe31c00a6ef80ed7d23f8163
diff --git a/dev-scripts/newplugin/executive.cpp.template \
b/dev-scripts/newplugin/executive.cpp.template index caa73ae..1dfe415 100644
--- a/dev-scripts/newplugin/executive.cpp.template
+++ b/dev-scripts/newplugin/executive.cpp.template
@@ -35,11 +35,42 @@
Nepomuk::${classname}::${classname}( int pluginVersion )
: Executive(pluginVersion)
{
+ // So, this is your constructor. What can you do here?
+ // First, everything defined here is accessible in your
+ // Reply class. So, you may create here a network infrastructure
+ // if you plugin use network(e.g. shared QNetworkAccessManager)
+ // BUT: be aware: Reply instances are created
+ // in different threads. So, EVERYTHING in here that is used by Reply class
+ // MUST be thread-safe.
+
+ // Add type filters.
+ // Type filters allow you to automatically reject resources with incorrect \
types. + // This way you may avoid typecheging in requestDecisions() method.
+ // to add type filter call
+ // addTypeFilter(<type url>, < match type>, <allowed> )
+ // Filters are operated as iptables. If resource type matches rule with allowed
+ // == true, then resource has passed. If matches the rule with allowed==false
+ // then rejected. Default rule can be set with setDefaultFilter(<allowed>)
+ // Match type is enum( see correct names in Executive class documentation) :
+ // Exact - exactly of given type
+ // Subclass - matches subclass of given type
+ // ExactOrSubclass - matches if subclass or given type or is the given type
}
-Nepomuk::WebExtractor::ExecutiveReply * \
Nepomuk::${classname}::requestDecisions(const WebExtractor::DecisionFactory * \
factory, const Nepomuk::Resource & res) +Nepomuk::WebExtractor::ExecutiveReply * \
Nepomuk::${classname}::requestDecisions(const Decision::DecisionFactory * factory, \
const Nepomuk::Resource & res) {
+ // If you have passed necessary options and inherited SimpleExecutive, then you
+ // are lucky - the Reply class was already generated for you. Otherwise you have
+ // to write it by yourself.
+ // In both cases what shoud you do here:
+ // 1. check some conditions - more complex type checks that are allowed by type
+ // filters, checks that some property do exist and so on
+ // 2. Check some enviroment if you want - like file is readable, network do \
exist + // , user have necessary permisions
+ // If all checks succeded - then create new instance of Reply class and return \
it + // Otherwise return NULL. Please do not create a special Reply instance for \
error + // situations - just return NULL.
#if $use_simple
return new ${name}Reply(this, factory, res );
diff --git a/dev-scripts/newplugin/executive.h.template \
b/dev-scripts/newplugin/executive.h.template index dcc9fbc..5d4eb2e 100644
--- a/dev-scripts/newplugin/executive.h.template
+++ b/dev-scripts/newplugin/executive.h.template
@@ -35,7 +35,9 @@ namespace Nepomuk {
{
Q_OBJECT
public:
- WebExtractor::ExecutiveReply * requestDecisions(const \
WebExtractor::DecisionFactory * factory, const Nepomuk::Resource & res) ; + // \
Main function your should impement. See source code file + // for more \
inforamtion. Or tutorials on *.kde.org + WebExtractor::ExecutiveReply * \
requestDecisions(const Decision::DecisionFactory * factory, const Nepomuk::Resource & \
res) ; ${classname}( int pluginVersion );
~${classname}();
friend class ${name}Reply;
diff --git a/dev-scripts/newplugin/executivereply.cpp.template \
b/dev-scripts/newplugin/executivereply.cpp.template index 6c2ac7b..8484777 100644
--- a/dev-scripts/newplugin/executivereply.cpp.template
+++ b/dev-scripts/newplugin/executivereply.cpp.template
@@ -45,6 +45,12 @@ Nepomuk::${classname}::${classname}(${name}Executive * parent, \
const WebExtracto ExecutiveReply((Nepomuk::WebExtractor::Executive*)(parent))
#end if
{
+ // In this method you may start extracting changes and submiting them. If you
+ // finish everything right in constructor, then you may call finish() method ( \
if + // you subclassed SimpleExecutiveReply) or should invoke finished() signal \
with + // connection type == Queued. This is IMPORTANT!
+ // For tutorial on extracting changes see tecbase.kde.org or \
SimpleResourceExecutive + // documentation
}
bool Nepomuk::${classname}::isValid() const
diff --git a/dev-scripts/newplugin/executivereply.h.template \
b/dev-scripts/newplugin/executivereply.h.template index e7cd7d4..4669036 100644
--- a/dev-scripts/newplugin/executivereply.h.template
+++ b/dev-scripts/newplugin/executivereply.h.template
@@ -37,11 +37,15 @@
namespace Nepomuk {
- namespace WebExtractor {
+ namespace Decision {
class DecisionFactory;
}
class ${name}Executive;
class Resource;
+ // Usually ( if you don't choose another design ) this
+ // is the class where all extracting stuff is done.
+ // Source file provides more explanation and advices. Or look
+ // for tutorials
#if $use_simple
class $classname : public WebExtractor::SimpleExecutiveReply
#else
@@ -50,9 +54,18 @@ namespace Nepomuk {
{
Q_OBJECT
public:
- ${classname}(${name}Executive * parent, const WebExtractor::DecisionFactory \
* factory, const Nepomuk::Resource & res ); + ${classname}(${name}Executive * \
parent, const Decision::DecisionFactory * factory, const Nepomuk::Resource & res ); + \
// Abort your execution. virtual void abort() ;
+ // It is up to you to decide is reply is valid or not.
+ // If it is not, it will be rejected.
virtual bool isValid() const ;
+ // If you subclassed 'SimpleExecutiveReply', you will
+ // have a method called 'decisions() that you should
+ // not reimplement as it provides nice functions.
+ // If you didn't subclass SimpleExecutiveReply, then
+ // you have to implement this method. It must returl
+ // list of all Decisions you have created
#if not $use_simple
virtual WebExtractor::DecisionList decisions() const;
#end if
diff --git a/dev-scripts/newplugin/plugin.cpp.template \
b/dev-scripts/newplugin/plugin.cpp.template index 822d5cf..562a72c 100644
--- a/dev-scripts/newplugin/plugin.cpp.template
+++ b/dev-scripts/newplugin/plugin.cpp.template
@@ -38,6 +38,11 @@ K_EXPORT_PLUGIN(${name}PluginFactory("webex${name.lower()}plugin"))
Nepomuk::${classname}::${classname}(QObject* parent, const QList<QVariant>&):
WebExtractorPlugin(parent)
{
+ // Usually there is nothing to do here. You may put here something that is \
common + // for ALL executives.
+ // Usually, infrastructure for network access is NOT what should be put here -
+ // for this use your Executive subclass
+ // So, if in doubts - dont put anything here
}
int Nepomuk::${classname}::version()
@@ -48,6 +53,15 @@ int Nepomuk::${classname}::version()
Nepomuk::WebExtractor::Executive * Nepomuk::${classname}::getExecutive(const \
KConfigGroup & configFile) {
kError() << "ATTENTION! Reimplement this! ";
+ // In this function you should parse your config file, read necessary parameters
+ // create new Executive with this parameters and return.
+ // in included file "${name.lower()}plugin_config.h" there is a define
+ // with name ${name.upper()}_CONFIG_GROUP. It is the name of config group
+ // you should use:
+ // KConfigGroup grp = configFile.group(${name.upper()}_CONFIG_GROUP)
+ // read settings from grp.
+ // Be aware that in given configFile there are not only your settings, but
+ // also some system settings too
return new ${name}Executive(version()/* add your parameters here */);
}
diff --git a/dev-scripts/newplugin/plugin.h.template \
b/dev-scripts/newplugin/plugin.h.template index c096781..f111a5e 100644
--- a/dev-scripts/newplugin/plugin.h.template
+++ b/dev-scripts/newplugin/plugin.h.template
@@ -29,6 +29,9 @@
namespace Nepomuk
{
+ // Actually, plugin is a factory for real plugins, called Executive.
+ // In method getExecutive you should parse config file and return a new \
executive + // Function version() is service function. No need to change it.
class ${name}Plugin : public WebExtractorPlugin
{
Q_OBJECT
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic