com.collabnet.core.ws.dispatcher
Interface DocumentHandler

All Known Implementing Classes:

GetSchemaHandler

public interface DocumentHandler

The DocumentAPIDispatcher delegates to DocumentHandlers to actually process incoming requests. There are 4 methods in the DocumentHandler:

• handle(Callcontext, XMLRequest, XMLResponse): Used to produce the response for a given request.,
• getHandledDocumentTypes(): Informs the framework what requests this handler can handle,
• getSchemaReferences(Callcontext, XMLRequest): returns references to schemas that represent the documents received and produced by this handler; and
• produceSchema(Callcontext, XMLRequest, SchemaVisitor): generates the schema that describes the documents this handler can receive and return.

handle: This is the workhorse method; it receives a Callcontext object, an XMLRequest and an XMLResponse object. You can use the XMLRequest object to find out what the incoming document was and you can use the XMLResponse to build the response document. The callcontext provides you with information such as Project, current User, ACL, etc.

getHandledDocumentTypes(): This must return an array of DocumentType objects. The Dispatcher framework calls this method to know which handler to invoke for a given incoming document. A DocumentType is simply a combination of namespace/xml name that corresponds to the root node of the incoming document.

getSchemaReferences(): This method can return references to schemas (one schema per namespace) that can be used to validate incoming and response documents.

produceSchema(): Generates the schema for this handler.

Let's look at a "HelloWorld" example. The HelloWorldHandler must receive a <greetWorld xmlns="urn:sample.com"/> and return <hello xmlns="urn:sample.com">World</hello>.

Let's start with getHandledDocumentTypes():

 
 public DocumentType[] getHandledDocumentTypes()
 {
     DocumentType[] types = new DocumentType[1];
     types[0] = DispatcherObjectFactory.getInstance().createDocumentType(
             "urn:sample.com", "greetWorld");
     return types;
 }
 
 

It says: The incoming documents I handle have a root node "greetWorld" in the "urn:sample.com" namespace. So, if the Dispatcher sees an incoming document like: <greetWorld xmlns="urn:sample.com"/> then the dispatcher will be able to find the HellowWorldHandler to handle the incoming document.

Now let's look at the handle() method:

 
 public void handle(Callcontext context, XMLRequest request,
         XMLResponse response) throws Exception
 {
     XMLVisitor visitor = response.getXMLVisitor();
     visitor.visit("urn:sample.com", "hello", "World");
 }
 
 

The first line obtains the XMLVisitor object from the response. The XMLVisitor's job is to help you construct the XML document response.

In this case we simply need to generate a document of the form: <hello xmlns="urn:sample.com">World</hello>

So, we can use the XMLVisitor.visit(namespace, tagname, value) method; this generates the above construct (though different implementations of the XMLVisitor interface may generate slightly different variants of the XML, but that's not our concern). Our concern is that we want to know how to use the XMLVisitor to generate XML. There are really 3 methods you need to know now:

• XMLVisitor.visit(String namespace, String tagName, String value): This can be used to generate <tagName xmlns="namespace">value</tagName>
• XMLVisitor.openNode(String namespace, String tagName): This can be used to generate <tagName xmlns="namespace">
• XMLVisitor.closeNode(String namespace, String tagName): This can be used to generate </tagName>

The other methods that refer to XMLObject interface are not yet used.

The addFilter/removeFilter methods are not yet used; the only known user of this may be the GetArtifactChanges handler.

Finally, getSchemaVisitor is only used by the dispatcher framework...

Author:

sszego

handle

void handle(Callcontext context,
            XMLRequest request,
            XMLResponse response)
            throws java.lang.Exception

This is the workhorse method; it receives a Callcontext object, an XMLRequest and an XMLResponse object. You can use the XMLRequest object to find out what the incoming document was and you can use the XMLResponse to build the response document. The callcontext provides you with information such as Project, current User, ACL, etc.

Parameters:

context - the current context

request - the current request

response - the response to generate

Throws:

java.lang.Exception - if an error occurs

getSchemaReferences

java.util.List getSchemaReferences(Callcontext context,
                                   XMLRequest request)
                                   throws SchemaReferenceException

Returns references to schemas (one schema per namespace) that can be used to validate incoming and response documents. Null maybe returned; if null is returned, then the framework will not perform automatic validation of incoming documents.

Parameters:

context - the current context

request - the current request

Returns:

the array of Schema references.

Throws:

SchemaReferenceException - if cannot obtain SchemaReference

getHandledDocumentTypes

DocumentType[] getHandledDocumentTypes()

Returns an array of DocumentTypeobjects that this DocumentHandler can handle. The Dispatcher framework calls this method to know which handler to invoke for a given incoming document.

Returns:

an array of DocumentType objects.

produceSchema

void produceSchema(Callcontext context,
                   XMLRequest request,
                   SchemaVisitor visitor)
                   throws SchemaGenerationException

Generates the schema for this handler.

A simple example:

A sample XML document:

<someTag xmlns="urn:sample.com">someStringValue </someTag>

To generate the XSD that describes the above document:

 
 visitor.visitXSDType("urn:sample.com", "someTag", XSDBaseType.XSDString);
 
 

Now a slightly more complicated example:

Sample document:

 
 
  
   
    
     
      
       
             <someTag xmlns="urn:sample.com">
               <someOtherTag xmlns="urn:sample.com/2">1234</someOtherTag>
               <someOtherTag xmlns="urn:sample.com/2">1235</someOtherTag>
               ...
             </someTag>
        
       
      
     
    
   
  
 
 

The code to generate the schema for the above document:

 
 visitor.startContainerElement("urn:sample.com", "someTag");
 visitor.startSequence();
 visitor.visitXSDTypeReference("urn:sample.com/2", "someOtherTag",
         XSDBaseType.XSDInt, "0", "unbounded");
 visitor.endSequence();
 visitor.endContainerElement("urn:sample.com", "someTag");
 
 

Parameters:

request - the current request

context - the current context

visitor - the SchemaVisitor to use.

Throws:

SchemaGenerationException

See Also:

XSDBaseType