The TaminoCommand class provides methods for
inserting, retrieving, updating and deleting documents. To get a
TaminoCommand object, use the
CreateCommand method in the
TaminoConnection object.
The methods work with two types of object:
An object that implements the ITaminoDocument
interface;
TaminoUri objects.
This chapter describes the most common ways of using those objects
together with the Insert,
Retrieve, Update and
Delete methods of the
TaminoCommand class. The chapter
Working with URIs describes more
advanced usage of the TaminoUri
class.
When working with Tamino documents, several different kinds of information are needed:
The actual data as stored in Tamino;
Information that characterizes the document, for instance whether it is XML or not;
Information that identifies the document in Tamino.
The ITaminoDocument interface encapsulates all
three kinds of information. It allows a Tamino XML document to be passed as a
self-describing object within the application.
An object of the TaminoUri class represents
information that describes how to find a document in
Tamino.
The Data property of the
ITaminoDocument interface holds the actual XML document.
In addition, the interface contains properties including the Tamino document
type and the document name that identify a Tamino XML document uniquely.
Depending on the operation, this identifying information must be specified
before the Insert, Update, Delete is called; alternatively, this information is
set from the TaminoCommand object before the method call
returns.
The value of the DocName property is
either the internal ID used by Tamino, or a unique name that the application
has given to the document. An internal ID always starts with a leading “@”. If
an application-specific unique name exists, the unique name takes
preference.
The Tamino API for .NET contains two
classes that implement the ITaminoDocument
interface:
SoftwareAG.Tamino.Api.TaminoDocument
SoftwareAG.Tamino.Api.Serialization.TaminoXmlDocument
This chapter focuses on the TaminoDocument
object. TaminoXmlDocument is more appropriate when
processing query results; for more information, see the section
Processing Document Lists.
A Tamino URI can be ether absolute or relative. In this chapter, all
TaminoURI objects are relative to the Tamino collection
of the TaminoCommand object. They have the following
structure:
Tamino_document_type/document_name
The document name can be either the Tamino internal D with a leading
“@” or the unique name that the application has given to the document. For more
advanced usage scenarios of the TaminoUri class, see the
chapter Working with URIs.
The following describes how to insert, update, retrieve and delete XML documents. For information about handling error situations, see the chapter Handling Responses and TaminoExceptions.
An application can insert XML documents with or without specifying a
unique name. In each case the TaminoCommand class sets
the DocType property to the correct value before
the method returns. If no unique name has been specified when calling
Insert, then the DocName
property of the ITaminoDocument interface will contain
the Tamino internal ID after the call.
The following shows how to insert an XML document without specifying a unique name. See also the InsertDocuments example in the SimpleSamples.
... // create a document XmlDocument doc = new XmlDocument(); doc.LoadXml(...); TaminoDocument tamDoc = new TaminoDocument(doc); command.Insert(tamDoc); ...
To insert an XML document with a unique name, set the
DocName property accordingly before calling the
Insert method. This name must not start with “@”. See
also the InsertWithName example in the Advanced Samples.
... // create a document XmlDocument doc = new XmlDocument(); doc.LoadXml(...); TaminoDocument tamDoc = new TaminoDocument(doc); tamDoc.DocName = "MyUniqueName"; command.Insert(tamDoc); ...
If you want to insert a document with a unique name and the XML
document uses namespaces, you must observe the following rule: If the name of
the Tamino document type is not the same as the fully-qualified name of the
document's root element, then you must set the
DocType property explicitly before calling the
Insert method.
Before updating or deleting an XML document, the DocName and DocType properties must contain valid values. This will automatically be the case if, for example, a preceding Insert or Retrieve has been processed.
If the application creates a new TaminoDocument
object from scratch, it must set the DocName
property. The DocType property is automatically
set to the fully qualified name of the document's root element. If namespaces
are being used and the fully-qualified name of the document's root element does
not match the name of the corresponding Tamino document type, the application
must set the correct DocType value explicitly.
When processing a delete command, it is not necessary to provide the
XML document itself. Therefore another option is to use the overloaded
Delete method, which takes a
TaminoUri object as parameter.
... TaminoDocument tamDoc = new TaminoDocument(doc); command.Insert(tamDoc); ... command.Delete(tamDoc); ...
...
command.Delete(new TaminoUri("./MyDocType/@1"));
...
... TaminoDocument tamDoc = new TaminoDocument(doc); tamDoc.DocName = "@1"; command.Update(tamDoc); ...
... TaminoDocument tamDoc = new TaminoDocument(doc); tamDoc.DocName = "@2"; tamDoc.DocType = "pre:MyDocType"; command.Update(tamDoc); ...
The Tamino API for .NET provides methods for retrieving documents and document properties . The most common cases are described below:
The application knows the identity of the document and wants to retrieve the document.
...
TaminoDocument tamDoc = command.Retrieve(new TaminoUri("Property/@1"));
...
.NET supports the generation of a programming language type from an
XML schema. These classes can then be used to process an XML document using the
programming language types instead of the DOM API. The Tamino API
for .NET allows an XmlDocument to be retrieved as a programming
language. All types which can be serialized and deserialized using .NET's
XmlSerializer class are supported.
...
Property property =
(Property) command.Retrieve(new TaminoUri("Property/@1"), typeof(Property));
...
For more convenient further processing, it is sometimes better to have
a Stream or XmlReader object
returned instead of a TaminoDocument.
...
Stream stream = command.RetrieveStream(new TaminoUri("Property/@1"));
...
...
XmlReader reader = command.RetrieveReader(new TaminoUri("Property/@1"));
...
The class TaminoDocumentProperties represents
properties, which can be retrieved from Tamino for a single document. One
example of these properties is the time when a Tamino document was most
recently modified. (For more information about the returned time format, see
the Tamino XML Server documentation.)
...
string lastmodifiedBefore = ...;
TaminoDocumentProperties properties = command.RetrieveProperties("Property/@1");
if ( properties.LastModified != lastmodifiedBefore )
Console.WriteLine("Document has changed");
...
If the application has already read a
TaminoDocument or
TaminoXmlDocument, TaminoCommand
provides facilities for re-reading the data from Tamino:
... TaminoTransaction tx = connection.BeginTransaction(); TaminoDocument tamDoc = new TaminoDocument(doc); TaminoResponse response = command.Insert(tamDoc); tx.Commit(); ... tx = connection.BeginTransaction(); // reload the data command.Retrieve(tamDoc); ... tx.Commit(); ...