Skip to main content
summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorspingel2008-02-29 02:38:07 -0500
committerspingel2008-02-29 02:38:07 -0500
commit19c98c013135e7f96e8aa5b96da1a8995097489c (patch)
treee9b902ad88575b6ac52b67a9650ba1aded05ec43
parent8625612e136473297822612affdbd2015a2a7813 (diff)
downloadorg.eclipse.mylyn.tasks-19c98c013135e7f96e8aa5b96da1a8995097489c.tar.gz
org.eclipse.mylyn.tasks-19c98c013135e7f96e8aa5b96da1a8995097489c.tar.xz
org.eclipse.mylyn.tasks-19c98c013135e7f96e8aa5b96da1a8995097489c.zip
NEW - bug 195450: [patch] improve documentation for APIs and extension point definitions
https://bugs.eclipse.org/bugs/show_bug.cgi?id=195450
-rw-r--r--org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/AbstractTaskListFactory.java113
1 files changed, 113 insertions, 0 deletions
diff --git a/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/AbstractTaskListFactory.java b/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/AbstractTaskListFactory.java
index 905ccb5f7..28f6e9aaf 100644
--- a/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/AbstractTaskListFactory.java
+++ b/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/AbstractTaskListFactory.java
@@ -31,32 +31,145 @@ public abstract class AbstractTaskListFactory {
public static final String KEY_TASK = "Task";
+ /**
+ * Returns true if factory can create an XML element to store given {@link AbstractTask}.
+ * <p>
+ * The name of the XML element is taken from the {@link #getTaskElementName()} method and
+ * additional task attributes can be stored in {@link #setAdditionalAttributes(AbstractTask, Element)} method.
+ *
+ * @param task
+ * a task instance to create XML element for
+ *
+ * @return true if factory can create XML element to store given {@link AbstractTask}.
+ *
+ * @see #getTaskElementName()
+ * @see #setAdditionalAttributes(AbstractTask, Element)
+ */
public abstract boolean canCreate(AbstractTask task);
+ /**
+ * Returns true if factory can create an XML element to store given {@link AbstractRepositoryQuery}.
+ * <p>
+ * The name of the XML element is taken from the {@link #getQueryElementName(AbstractRepositoryQuery)} method and
+ * additional query attributes can be stored in {@link #setAdditionalAttributes(AbstractRepositoryQuery, Element)}.
+ *
+ * @param query
+ * a query instance to create an XML element for
+ *
+ * @return true if factory can create XML element to store given {@link AbstractTask}.
+ *
+ * @see #getQueryElementName(AbstractRepositoryQuery)
+ * @see #setAdditionalAttributes(AbstractRepositoryQuery, Element)
+ */
public boolean canCreate(AbstractRepositoryQuery query) {
return false;
}
+ /**
+ * Creates an {@link AbstractRepositoryQuery} instance from given XML element matching one of the names returned by
+ * {@link #getQueryElementNames()}.
+ * <p>
+ * Concrete implementation should populate required query configuration using method parameters and content of the
+ * passed XML element. Children tasks for this query instance will be created by the caller of this method.
+ *
+ * @param repositoryUrl
+ * an url for the corresponding task repository
+ * @param queryString
+ * a query string, e.g. connector-specific url used for query request
+ * @param label
+ * a query label or name
+ * @param element
+ * an XML element containing query data
+ * @return instance of the {@link AbstractRepositoryQuery}
+ *
+ * @see #getQueryElementNames()
+ */
public AbstractRepositoryQuery createQuery(String repositoryUrl, String queryString, String label, Element element) {
return null;
}
+ /**
+ * Creates an {@link AbstractTask} instance from given XML element matching name returned by
+ * {@link #getTaskElementName()}.
+ * <p>
+ * Concrete implementation should populate required task data using method parameters and content of the passed XML
+ * element. Children tasks of this task instance will be created by the caller of this method.
+ *
+ * @param repositoryUrl
+ * an url for the corresponding task repository
+ * @param queryString
+ * a query string, e.g. connector-specific url used for query request
+ * @param label
+ * a query label or name
+ * @param element
+ * an XML element containing query data
+ * @return instance of the {@link AbstractRepositoryQuery}
+ *
+ * @see #getTaskElementName()
+ */
public abstract AbstractTask createTask(String repositoryUrl, String taskId, String label, Element element);
+ /**
+ * Returns name of the XML element used to store given query instance if {@link #canCreate(AbstractRepositoryQuery)}
+ * return true for given query instance.
+ *
+ * @param query
+ * a query instance to get the name for
+ *
+ * @return name for the XML element to store given query instance or null if factory doesn't support given
+ * {@link AbstractRepositoryQuery} instance.
+ *
+ * @see #canCreate(AbstractRepositoryQuery)
+ */
public String getQueryElementName(AbstractRepositoryQuery query) {
return "";
}
+ /**
+ * Returns names for all query elements.
+ * <p>
+ * This collection is used to determine if this factory can create {@link AbstractRepositoryQuery} instance from the
+ * XML element using {@link #createQuery(String, String, String, Element)} method.
+ *
+ * @return a <code>Set</code> of query element names
+ *
+ * @see #createQuery(String, String, String, Element)
+ */
public Set<String> getQueryElementNames() {
return Collections.emptySet();
}
+ /**
+ * Returns name for the XML element used to store subclass of the {@link AbstractTask} used by this factory. This
+ * value is used to create an XML element when storing given {@link AbstractTask} as well as to determine if this
+ * factory can read XML element with content of the task.
+ *
+ * @return name of the task element
+ *
+ * @see #canCreate(AbstractTask)
+ */
public abstract String getTaskElementName();
+ /**
+ * Adds additional attributes to an XML element used to store given {@link AbstractRepositoryQuery}.
+ *
+ * @param query
+ * a query instance being stored
+ * @param node
+ * an XML element used to store given query instance
+ */
public void setAdditionalAttributes(AbstractRepositoryQuery query, Element node) {
// ignore
}
+ /**
+ * Adds additional attributes to an XML element used to store given {@link AbstractTask}
+ *
+ * @param task
+ * a task instance being stored
+ * @param node
+ * an XML element used to store given task instance
+ */
public void setAdditionalAttributes(AbstractTask task, Element element) {
// ignore
}

Back to the top