The functionality of the GCF

After the introduction to the components of the GCF, some more information on how they work together shall be given in this chapter. Figure one shows the dependencies of the components.

Figure 1 : The dependencies of the components of the GCF

As you can see, this UML diagram shortly summarizes the relations, which have already been described in the chapter before. The first thing that's conspicious is the central position of the GXLConverterAPI. Its task is the management of the GXLConnector and the GXLDocumentHandler. It is important that the GXLConverterAPI cannot hold more than one instance of the GXLConnector / GXLDocumentHandler at the same time. The GXLDocumentHandler is a port of the integrated XML parser. It passes the generated events on to the GXLConnector. To do so, the GXLDocumentHandler needs to get an instance of the GXLConnector.

There is a unidirectional relation between the GXLConnector and the abstract class hierarchy because the GXLConnector calls the right methods of the abstract class hierarchy  to handle the incoming parser events. In the other direction no data exchange is necessary.

It can be useful for the user implementation of the abstract class hierarchy to use some functionality of the GXLConverterAPI (e.g. the getResultObject() method). In the other direction, the GXLConverterAPI saves an instance of the GXLGXLAPIImpl so that there is a bindirectional relation between these components.

The GXLOutputAPI can be used by the user implementation of the abstract class hierarchy to output the result of the conversion. This fact is expressed by a unidirectional relation.

A pretty good method to describe the way the GCF works is to show the internal data stream in a sequence diagram. This shall exemplarily be done by showing what happens after the startElement event has been raised. Figure two shows the event handling.

     Figure 2  : Handling of the startElement  event

In the sequence diagram above you can see that the parser calls the method startElement(name) of the GXLDocumentHandler when it finds a XML/GXL construct of type name. After that the GXLDocumentHandler passes the event handling on to the GXLConnector by calling the method create(name). Now the GXLConnector realizes that a construct of type name shall be created and tests the depth of the internal stack (see components for further information). If the depth is 0 (i.e. the stack is empty), there is no current construct (because the method create() is called the first time) and the construct that shall be created is the implementation of the GXLGXLAPIImpl. This object was already given to the GXLConnector (by calling the methods createGXL() and createConnector() of the GXLConverterAPI) so that there's no need to create a new one. If the current depth is one or higher, a new object has to be created and attached to the current construct. This is done by calling the appropriate method in the abstract class hierarchy. If for example the current construct is of type graph and a node shall be created, the method createNode() of the GXLGraphAPIImpl is called.The remaining procedure is the same in both cases (currentDepth=0 or currentDepth>0). The new construct is put on the stack and the current depth is increased by one. To make the value of the current depth accessible for the user, it is set in the GXLOutputAPI by calling the method setCurrentDepth(currentDepth+1).

Having analysed the use cases of the GCF, two implementations of the abstract class hierarchy seem to be very useful. These two implementations shall be described in the next chapters (default implementation 1, default implementation 2).