Evaluation Guide

This document describes the best way to quickly evaluate the product.

Getting started

Before you Start : If your not sure what XML Data Binding is, then read this article first (5-10 minutes)

Want something to look at?

If your the type of person that needs to see something visual before spending more time reading through the docs, then this sample is for you. We've constructed a simple viewer that allows you to visualize the generated code library (this is currently only available for C#, but the concepts are transferable to other the languages).

Start Small

It may be tempting to rush in and throw the biggest most complicated schema you have at our product and see what happens (and at some point I imagine you will do just that). However, initially this approach is a counter productive, the code generated would be overwhelming (if you don't know where to start), so we advise the walk before you can run approach.

Find a small straight forward schema, ideally one that you have couple of sample XML files for (if you don't have one, download one from somewhere or use the Bookstore.xsd sample provided).

Use the wizard to generate code in your chosen language (ignore any options you don't understand for now, refer to the Wizard Help for more detail if you want)
A word about languages The structure of the generated code is the same for all languages. So what you get for C# is comparable to what you get when generating C++, VB.Net, VB6 and java.

It should also be noted that there are additional tools provided with the C# code that show more clearly what is being generated, and how to use it.
As the code for all languages is very similar in structure, we strongly recommend (if you have Visual Studio .Net installed, and some .net experience) that you start by generating C# code (even if that is not your target language), and later look at the code for your chosen language.

The sample file should contain a number of section that looks something like this.

/* --------------------------------------------------------------------------------- * This function can be used to open an XML document with a document element * (the first element in the file) named 'QuoteRequest' * e.g. * * <?xml version="1.0" encoding="UTF-8"?> * <QuoteRequest> * ... * </QuoteRequest> * --------------------------------------------------------------------------------- */ SimpleTestPriceEnquirySampleLibQuoteRequest(@"<UNCOMMENT & INSERT A SAMPLE XML FILENAME HERE>");

Now is a good time to open up your sample XML file (one that is compliant with the schema), and check what the root element is, in the sample below it is QuoteRequest.

Within the sample code there will be an entry that corresponds to your root element. Find it, un-comment it and add in the path to your sample file (in VB you can do this at runtime using the sample app UI).

SimpleTestPriceEnquirySampleLibQuoteRequest(                     @"C:\Program Files\Liquid Technologies\XMLDataBinder3\ClientSamples\QuoteRequest.xml");

When the sample app is run,

• An object specific for the root element in your XML document will be created.
• Your sample XML file will be loaded into this object.
• If you are using C#, then the object is displayed in a watch window style viewer (more about than in a minute)
• The object is serialized back to XML
• The Xml is written out.
• If any error occur they are displayed.

If you are using C# then you will see the object viewer window, this is a fantastic way to quickly get a feel for what the generated class library looks like and how it works.

Using the viewer you can quickly get a feel for the structure of the class library. What you see in the tree is a reflected view of the actual objects. Furthermore using the context menus, you can modify the data contained in the tree, adding nodes, changing values etc.

As you select each node you see the XML that is container within it. The code tab shows the C# source required to create an object in this state (ideal for prototyping).

So if your not working with C# you may feel a little left out, but not really. As I mentioned before the structure of the objects is same in all the languages, so what you see for C# is 99% the same as what you see in C++ & Java (VB has a few more differences).

Getting stuck into the code

I guess by now you want to get you feet wet, and actually do some coding. We will soon (promise), but first lets look at a simple sample.

Lets park what we were looking at for now, and open up the PriceEnquirySample workspace file.

This is a simply sample based around the PriceEnquiry schema

The sample shows both sides of a request/response system (the server part would normally be a remote server in the real world, but this is just a sample). In this scenario the client is asking for a quote for several items, the server checks the items availability and price and returns this information to the client.

• (Client) First it builds up the request using the QuoteRequest object.
• (Client) The QuoteRequest object is converted to XML and passed to Request Servicing function.
• (Server) The request XML is reloaded into a QuoteRequest object
• (Server) Using the data in the QuoteRequest object, the stock list is checked.
• (Server) A QuoteResponse object is constructed and populated based on stock levels.
• (Server) The QuoteResponse object is then converted to XML and returned.
• (Client) A QuoteResponse object is constructed from the response XML
• (Client) The response is displayed in a human readable form.

So now you've see the Sample, it should be a little easier to write code based on your own sample XSD.

Documentation

On final thing before you dive in; Generated alongside the code (unless you deselected it in the wizard) is a set of documentation to go with the class library. This takes the form of an CHM (compiled help file). In order to build it you will need the Help workshop (Free from Microsoft, and installs with VS.Net). To build it just run the DocumentationXXX\build.bat.

The resulting document describes all the objects in the class library, and how they relate. For more general help see LtHelp.chm (which is also in the DocuemntationXXX directory).

Coding

I suggest you start by creating a new object, and populate it programmatically (the C# object viewer can help with this part), also refer back to the help & and sample app. Then write code to load up the sample XML file, and navigate around the object representation. If you have any specific requirements, multi language (Unicode,UTF-8 etc), performance, etc this is also a good time to prove to yourselves that things work.

If you have any problems, please contact our support staff, its what there here for!
Create Support Ticket

Finally the big test.

I know your going to want to do this, but it really is worth waiting until you've covered the basics first. Your going to take the biggest schema you work with and throw that against the wizard.

So with a bit of luck your schema is valid, and you've just generated a load of code and documentation. If your schema uses any of the more advanced features substitution, extensions etc, then you should refer to the samples in the LtHelp.chm file for more details about dealing with these features.

So what if the wizard failed to generate code?

The most common cause of problems is an invalid schema. The XSD standard is complex, and many developers have taken subtly different views on how it should be interpreted. Because of this some tools allow you to produce invalid schema's.
We use the Microsoft parser (MSXML).If MSXML considers the schema invalid then you will get an error that looks something like this, at this point you'll need to fix the problem before continuing.

If you are having problems doing this then please contact us, and we will help if we can.
Create Support Ticket

If you get any other errors, then please contact us, we are committed to continually improving our product, and will do our best to resolve the issue (generally pretty quickly).

Having evaluated our product, if you have any feedback for us (good or bad), any suggestions, or questions, then please take the time to mail us.

Thanks for evaluating our product, we hope you liked it.