Insert a Stub into a Repository
The stub
fetch action inserts a stub into a repository.
A stub is a link to a document in another repository. An application might use your connector to insert a stub when a document is moved to another repository or is deleted. The stub can point to the new location, or in the case where the document has been deleted, explain why the document is missing.
Action | Description | Method to override |
---|---|---|
/action=fetch&fetchaction=Stub
|
Inserts a stub into a repository. | Stub
|
Before you implement the stub
action, enable the action by updating the features()
function on the connector so that it returns Features::stub
:
Features::feature_type MyConnector::features() { return ... | Features::stub; }
To implement the stub
action, override the stub
method.
When your users run the Stub
action, they must set an action parameter named StubXML
. The value of this parameter is XML that describes the stub documents to insert. ConnectorLib C++ uses the XML to provide DocInfo
objects, which are available through the StubTask
object provided to the stub
method.
You must use the reference, identifier, properties, and metadata contained by a DocInfo
object to determine where to insert the stub. You should instruct the users of your connector what information they must provide.
To determine the target of the stub document (the document that the stub must point to), use the method task.target(doc)
. This returns a StubTarget
object that can include any of the following properties:
- The name of a connector group that can retrieve the stub target.
- A document identifier that can be used by a connector to retrieve the stub target.
- A URI that can be used to retrieve the stub target.
- A RedirectHtml string. When opened in a Web browser this should open the stub target.
If your code inserts the stub successfully, call the success
method on the relevant DocInfo
object. If there is a problem, call the failed
method with a description of the error that can be reported to the user.
Example
The following example code shows how to implement the stub action for a simple file system connector.
This example code calls a function named createStubForDocument
(that you must implement) to insert one or more stubs into the repository. The target is the location of the actual document that the stub must refer to. You should extract the location of each stub from the DocInfo
object.
void MyConnector::stub(const StubTask& task) { const DocInfoList& documents = task.documents(); for (std::size_t ii = 0; ii < documents.size(); ++ii) { try { DocInfo doc = documents[ii]; StubTarget target = task.target(doc); createStubForDocument(doc, target); doc.success(); } catch (std::exception& ex) { doc.failed(ex.what()); } } }