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());
        }
    }
}