GXL2<...> conversion

The following chapter describes how to implement a running GXL2<...> converter on the base of the GCF. Because it is impossible to cover all possible use cases, two of the most often used shall be explained. The first one is that you would like to implement a converter which parses the GXL document, converts the constructs and then outputs the result. The second possible use case is that you want to manipulate the structure of the source document before you convert it.

The way the GCF works in the first variant is shown in figure 1.

Figure 1 : GXL2<...> conversion  without manipulating the syntax tree of the source document

In figure 1 you can see that the conversion is started by parsing the source document. In this case the source document is an XML file, so that you can use the integrated AElfred parser. The parser generates several events during the parsing. The GXLDocumentHandler then passes these events on to the GXLConnector which calls the appropriate method in the user's implementation of the abstract class hierarchy. The implementation converts the GXL constructs and then uses the GXLOutputAPI to output the result.

The blue marked components in figure 1 are already provided by the GCF so that the user only has to implement the abstract class hierarchy and to initialize the GCF. It is important to know how to "interprete" the methods of the abstract classes. An easy way is to let yourself guide by a question. If you for example want to implement the method createGraph() of the GXLGXLAPIImpl, you can ask : "What shall be done when the current construct is of type gxl and a child element of type graph is created ?"

As you'll see in the following, it is pretty easy to initialize the GCF because you can use the functionality of the GXLConverterAPI. Table 1 shows the method calls that have to be done and what they result in.

Table 1 : Method calls that are necessary for the initialization of the GCF

It is important to generate the method calls in the same order as shown in table 1. This is necessary because the GXLConnector needs the URL and the package name of the user implementation of the abstract class hierarchy, and the GXLDocumentHandler needs the GXLConnector to get initialized properly. For more information on how to set the URL and the package name, have a look at the GXLConverterAPI in the chapter about the components.

The initialization of the GCF for this use case is demonstrated in a demo file as well.

If you want to manipulate the document structure before you convert it, some more efforts are necessary. Figure 2 shows how the GCF works in this use case.

Figure 2 : GXL2<...> conversion  with manipulation of the syntax tree of the source document

The conversion starts in the same way as in the first use case. The source document is parsed and the generated events are passed on to the GXLDocumentHandler and then to the first instance of the GXLConnector. As you can see, the GXLConnector has to be instantiated with the default implementation 2, so that the syntax tree of the source document is generated. After that you can manipulate the syntax tree. Then you have to create a second instance of the GXLConnector which uses the user implementation of the abstract class hierarchy, so that the manipulated source document can be converted. After that the GXLOuptutAPI can be used to output the result and the conversion is complete.

So in this use case the user has only to implement the abstract classes, to provide some methods to manipulate the syntax tree and to initialize the GCF two times  to build a running GXL2<...> converter. The initialization of the GCF works in the same way as shown above.

There's also a demo file that shows how to initialize the GCF. This demo file also provides a method that traverses the syntax tree of a document and generates the input for an instance of the GXLConnector. This method is necessary after you've manipulated the syntax tree of the source document.