I wrote the following maybe...2 years ago? I've put the actual software into production and have demonstrated it in a classroom environment. The initial thinking here was to bridge the gap between SOAP and OOP. As of now, unless something has changed, web services doesn't support this sort of thing, nor does SOAP on any platform.

So....I came up with this. Guess what? I could use this for a lot of other things as it's so generic, you can use it for just about anything from config files to email exceptions from errors, resource scripts for languages, private label stuff, etc.

Does anyone give a freakin' dang? I guess not as no professor paid one bit of attention to it, no collegiete director, no PM, no client of any staffing firm, or any other recruiter. I've emailed this document to a load of people, and I think nobody understands it. If I had someone to do this the same way on a Java basis, you could readily integrate cross platform stuff using OOP, and there is a demand for it. Then again, I'm just some long haired freak who wears high dollar silk shirts to work with funky colors, and I run numbers and engineering through my head all day long. I see the whole picture like a kid with legos. I see the pieces and the final result.

For some reason, that's a very bad thing-particularly around my neck of the woods. /:)

So without further ado, here is the copy and paste version from MS Word of what I plan on using for my Mob Manager tool. This is my code, and my documentation.

XML API

Introduction

This documentation is to outline the XML Object API. The purpose of the API is to allow a developer to create, serialize, and populate user defined objects using XML. This functionality has a wide variety of applications, and can be used nearly anywhere that XML is used.

Let's assume we have a given object, and we wish to save it as XML.

using System;

using System.Collections.Generic;

using System.Text;

using System.Reflection;

namespace TestObject

{

public class MyObject

{

private int m_int;

private string m_myString="";

public MyObject()

{

//Add additional constructor stuff here.

}

public int MyInteger

{

get{return this.m_int;}

set{m_int=value;}

}

public string MyString

{

get { return m_myString; }

set { m_myString = value; }

}

~MyObject()

{

m_myString="";

m_myString=null;

}

}

}

Fig 0.1-1

We can always write a custom parser to load XML, and to create some sort of schema that saves XML to a file. We can do that each any every time we write a class.

If we inherit the RuntimeXML class from the XML Object API, we have this functionality built in already. The RuntimeXML base class has everything we need to populate an object from XML, save it to XML, or pass in a properly formatted XML document to populate our object when we instantiate it.

using System;

using System.Collections.Generic;

using System.Text;

using System.Reflection;

using XML_Utilities;

namespace TestObject

{

public class MyObject : RuntimeXML

{

public static int intInstances;

private int m_int;

private string m_myString="";

public MyObject()

{

//Add additional constructor stuff here.

}

//This populates the current instance with data based \

//on the XML we provide it with.

public MyObject(string strXML)

{

//We explicitly define the type to pass in as

//the type of objec this is.

this.CreateFromXML(strXML,typeof(MyObject));

}

public int MyInteger

{

get{return this.m_int;}

set{m_int=value;}

}

public string MyString

{

get { return m_myString; }

set { m_myString = value; }

}

~MyObject()

{

m_myString="";

m_myString=null;

}

}

}

Fig 0.1-2

Criteria

In order to best make use of the XML Object API, there are some criteria/guidelines that you should follow and implement in your code to avoid problems and make the best use from the API.

• Your object must inherit one of the classes in the API. These classes are RuntimeXML, ArrayListXML, ListXML, and DictionaryXML. If you do not inherit these classes in your implementation, and you attempt to use the functionality of the API, problems are inevidable.

• Your custom objects should be lightweight objects with properties that can both read and write. If your object has other methods and functions, the API will not look at those because it only looks for properites at runtime. Failure to ensure that properties are readable and writeable may result in runtime exceptions from limiting the fucntionality of your object.

• If you choose to implement other custom objects or collections that will benefit from the functionality of the API, then you need to follow the same criteria as above. This is particularly important if you are using anything with nested objects, or nested collections, or a combination thereof.

NOTES:

• It is possible to use properties of type Object when implementing your custom class. However, the support for this is limited. If you're object is going to be any primative type, this functionality is supported. There is a conversion class with the framework that will convert your object to a strict primative. However, it is best to use a more descriptive declarative in your design. If you try to declare an Object, and assign it a value of another user defined type, problems will arise. It is best to avoid the use of type Object or any equivalent within the .NET framework and use a more explicit type.

• You can use other nested types of objects in your custom implementation. However, you need to ensure that each of those custom user types inherit one of the base classes from the XML Object API in order for it to function correctly.

• When using nested objects, you need to keep track of which objects you are using regardless of where they fall in the tree. A custom object may not live in your root object where nesting begins, but it may become pertinent to know that it is used at some point later in the tree.

• You may find yourself in need of inheriting a custom object that inherits a class from the XML Object API. You may also find that another inherited class needs the same functionality. In such a case, it is a good idea to implement a custom interface for your object, and implement the interface in your other object that inherits something else. You can alwayws encapsulate the logic from your own custom object that inherits from the XML Object API. Custom objects can be members of other objects that don't make use of the XML Object API.

1.0 Functions and methods within the RuntimeXML Class.

1.1. CreateFromXML

There are 2 different overloaded types within the base class.

virtual public void CreateFromXML(string strXML,Type t)

virtual public void CreateFromXML(string strXML, Type t, Dictionary<object, object> Objects)

These methods live within the RuntimeXML base class. They populate an instance of an object that inherits this class from the XML that you pass to it, the type, and if there are other user defined types nested within your object, you need to use the latter of the two.

strXML

This is the XML document describing your object, and all it's public properties as a string.

t

T is the type of object you are wanting to create. You can obtain this by using the GetType method of a given object. GetType returns a System.Type object, which is what this function uses.

Type Example

CreateFromXML(strXML,typeof(MyObject));

CreateFromXML(strXML,m_object.GetType());

You can use either typeof([Object_Name]) or [Object_Name].GetType() to obtain a System.Type object for use in this method.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 1.2-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

1.2. CreateXML

public string CreateXML(Type t)

public string CreateXML(Type t, Dictionary<object, object> Objects)

This creates an XML document that describes your object at runtime. Your custom object will dynamically discover it's own properties at runtime and obtain information as to the property name, type, and value.

The first declaration is for primitives, and the second is for objects that have other user defined types within them.

t

T is the type of object you want to populate. You can obtain this by using the GetType method of a given object. GetType returns a System.Type object, which is what this function uses.

Type Example

CreateXML(typeof(MyObject));

CreateXML(m_object.GetType());

You can use either typeof([Object_Name]) or [Object_Name].GetType() to obtain a System.Type object for use in this method.

Objects

In the event that you have other user defined or non-primative types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 1.3-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

Usage Example

TestObject.MyObject oTest = new TestObject.MyObject();

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

string strXML=oTest.CreateXML(typeof(TestObject.MyObject),oDict);

Fig 1.3-2

This illustrates how to create the XML from a custom object at runtime. The result is returned to strXML as a string. The string has the XML that explicitly describes the object.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

1.3. Load

virtual public string Load(string strFileName)

This loads an XML document, reads the entire file, and returns a string representation of the XML within the document. You must provide the complete file path as well as the file name for strFileName.

If your file is invalid, or doesn't exist, an exception will be thrown. The inner workings of this function uses a file stream reader object.

Usage Example

oTest = new TestObject.MyObject();

strXML = oTest.Load(Application.StartupPath + "\\Test Object.xml");

oTest.CreateFromXML(strXML,oTest.GetType(),oDict);

strXML = oTest.CreateXML(oTest.GetType(), oDict);

oTest.SaveXML(Application.StartupPath + "\\Test Object from file.xml",strXML);

Fig 1.4-1

This illustrates how to load an XML file using the Load function. The file is read, and it returns a string representaiton of the XML descibing a user defined object. The XML can then be used and manipulated to populate the object using the CreateFromXML method.

NOTE:

• This does not validate the format of your XML. This function merely loads the file and reads it if it in fact exists. If you wish to validate your XML, there are other means to do that with, or you can implement your own custom XML validator if you wish.

1.4. SaveXML

virtual public void SaveXML(string strFileName, string strXMLDoc)

virtual public void SaveXML(Type t, Object o,string strFileName)

These methods save XML files that explicitly describe your document. Each overloaded declaration works differently from the next one.

If you have a copy of the XML string that describes your object, you can pass that in along with a file name. The file name should include the complete path of your file as well as the filename itself. This uses a stream writer object when invoked to create the XML file.

NOTES:

• If you do not have a string that represents the XML describing your custom object, then you should use the second function. If you do not know what the XML is at runtime, and you are not using anything besides primative data types, use this function.

• However, if you are using custom objects within your root custom object, or anything that deals with nested custom objects, DO NOT USE THE SECOND FUNCTION.

The second function makes an internal call to the CreateXML function for an object of type t, from instance o. It then takes that XML, and passes it to the first function to save it to a file. There is no support for a function to serialize XML to a file whose XML is not known, and who's object has other user defined objects within it. Future versions or releases may support this. Therefore, it is suggested to use the first function if possible.

t

T is the type of object you want to populate. You can obtain this by using the GetType method of a given object. GetType returns a System.Type object, which is what this function uses.

Type Example

SaveXML(typeof(MyObject), m_object,strFileName);

SaveXML(m_object.GetType(), m_object,strFileName);

You can use either typeof([Object_Name]) or [Object_Name].GetType() to obtain a System.Type object for use in this method.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 1.5-1

Usage example

string strXML=oTest.CreateXML(typeof(TestObject.MyObject),oDict);

//Save the file as XML

oTest.SaveXML(Application.StartupPath + "\\Test Object.xml", strXML);

oTest.Dispose();

oTest = null;

Fig 1.5-2

The above illustration demonstrates how to create an XML document using the CreateXML method. From there, you pass that string into the SaveXML method. The complete path is determined dynamically at runtime and concatenated with the actual file name.

NOTE:

• However, if you are using custom objects within your root custom object, or anything that deals with nested custom objects, DO NOT USE THE SECOND FUNCTION.

1.5. Dispose

public void Dispose()

This function is inhertiable by your custom object, and is a standard implementation of the IDisposable interface. While the class RuntimeXML doesn't implement this particular interface, the functionality is the same.

NOTE:

• It is suggested that you call Dispose when you're done with your object whenever possible. There are various resources within the API that are used, and to be properly released, proper resource management can help performance and avoid other issues related to the lack of management of resources.

2.0 Functions and methods within the ArrayListRuntimeXML Class.

This class is derived in part from ArrayList. ArrayList is parent object from which objects within this class originate from.

2.1 Constructors

public ArrayListRuntimeXML()

public ArrayListRuntimeXML(string strXML,ArrayListXML oList, Dictionary<object,object> Objects)

The first constructor is a standard default contstructor. If you wish to populate your ArrayList from an XML document, and your array has other custom user defined types, the second constructor exists for that reason.

strXML

This is the XML document describing your object, and all it's public properties as a string.

oList

This is an ArrayListXML class. Since classes are passed by reference vs. value in .NET, an empty instance can be passed in.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 2.1-2

2.2. CreateFromXML

There are 2 different overloaded types within the base class.

virtual public void CreateFromXML(string strXML, ArrayList oList)

virtual public void CreateFromXML(string strXML,ArrayList oList, Dictionary<object,object> Objects)

These methods live within the ArrayListXML base class. They populate an instance of an object that inherits this class from the XML that you pass to it, the type, and if there are other user defined types nested within your object, you need to use the latter of the two.

strXML

This is the XML document describing your object, and all it's public properties as a string.

oList

This is an array list that you want to pass in, or it can be a type of ArrayListXML class. Array list inherits from the ArrayList class, so you can pass that in since the base type matches the interface argument.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 2.2-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

Usage Example

oArrayXML = new XML_Utilities.ArrayListXML();

strXMLDoc = oArrayXML.Load(Application.StartupPath + "\\Test Array List.xml");

oArrayXML.CreateFromXML(strXMLDoc, oArrayXML,oObjects);

oArrayXML.SaveXML(Application.StartupPath + "\\Test Array List from file.xml", oArrayXML.CreateXML(oArrayXML, oObjects));

//Save the file as XML

oArrayXML = null;

Fig 2.2-2

This illustrates how to use the CreateFromXML method. The XML is obtained by loading a file, and the resulting string is passed into the argument. The object oArrayXML is then populated based on the data passed into it.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

2.3. CreateXML

virtual public string CreateXML(ArrayList oList)

virtual public string CreateXML(ArrayList oList, Dictionary<object, object> Objects)

This creates an XML document that describes your object at runtime. Your custom object will dynamically discover it's own properties at runtime and obtain information as to the property name, type, and value.

The first declaration is for primitives, and the second is for objects that have other user defined types within them.

oList

This is an array list that you want to pass in, or it can be a type of ArrayListXML class. Array list inherits from the ArrayList class, so you can pass that in since the base type matches the interface argument.

Objects

In the event that you have other user defined or non-primative types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 2.3-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

string strXMLDoc = oArrayXML.CreateXML(oArrayXML,oObjects);

Fig 2.3-2

This illustrates how to create the XML from a custom object at runtime. The result is returned to strXML as a string. The string has the XML that explicitly describes the object.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

2.4. Load

virtual public string Load(string strFileName)

This loads an XML document, reads the entire file, and returns a string representation of the XML within the document. You must provide the complete file path as well as the file name for strFileName.

If your file is invalid, or doesn't exist, an exception will be thrown. The inner workings of this function uses a file stream reader object.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oArrayXML = new XML_Utilities.ArrayListXML();

strXMLDoc = oArrayXML.Load(Application.StartupPath + "\\Test Array List.xml");

oArrayXML.CreateFromXML(strXMLDoc, oArrayXML,oObjects);

oArrayXML.SaveXML(Application.StartupPath + "\\Test Array List from file.xml", oArrayXML.CreateXML(oArrayXML, oObjects));

//Save the file as XML

oArrayXML = null;

Fig 2.4-1

This illustrates how to load an XML file using the Load function. The file is read, and it returns a string representaiton of the XML descibing a user defined object. The XML can then be used and manipulated to populate the object using the CreateFromXML method.

NOTE:

• This does not validate the format of your XML. This function merely loads the file and reads it if it in fact exists. If you wish to validate your XML, there are other means to do that with, or you can implement your own custom XML validator if you wish.

2.5. SaveXML

virtual public void SaveXML(string strFileName, string strXMLDoc)

virtual public void SaveXML(Type t, Object o,string strFileName)

These methods save XML files that explicitly describe your document. Each overloaded declaration works differently from the next one.

If you have a copy of the XML string that describes your object, you can pass that in along with a file name. The file name should include the complete path of your file as well as the filename itself. This uses a stream writer object when invoked to create the XML file.

NOTES:

• If you do not have a string that represents the XML describing your custom object, then you should use the second function. If you do not know what the XML is at runtime, and you are not using anything besides primative data types, use this function.

• However, if you are using custom objects within your root custom object, or anything that deals with nested custom objects, DO NOT USE THE SECOND FUNCTION.

The second function makes an internal call to the CreateXML function for an object of type t, from instance o. It then takes that XML, and passes it to the first function to save it to a file. There is no support for a function to serialize XML to a file whose XML is not known, and who's object has other user defined objects within it. Future versions or releases may support this. Therefore, it is suggested to use the first function if possible.

t

T is the type of object you want to populate. You can obtain this by using the GetType method of a given object. GetType returns a System.Type object, which is what this function uses.

Type Example

SaveXML(typeof(MyObject), m_object,strFileName);

SaveXML(m_object.GetType(), m_object,strFileName);

You can use either typeof([Object_Name]) or [Object_Name].GetType() to obtain a System.Type object for use in this method.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 2.5-1

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oArrayXML = new XML_Utilities.ArrayListXML();

strXMLDoc = oArrayXML.Load(Application.StartupPath + "\\Test Array List.xml");

oArrayXML.CreateFromXML(strXMLDoc, oArrayXML,oObjects);

oArrayXML.SaveXML(Application.StartupPath + "\\Test Array List from file.xml", oArrayXML.CreateXML(oArrayXML, oObjects));

//Save the file as XML

oArrayXML = null;

Fig 2.5-2

The above illustration demonstrates how to create an XML document using the CreateXML method. From there, you pass that string into the SaveXML method. The complete path is determined dynamically at runtime and concatenated with the actual file name.

3.0 Functions and methods within the ListRuntimeXML Class.

This class is derived in part from List. List is parent object from which objects within this class originate from. Although List is a typed list, that functionality more or less vanishes as the implementation of this class uses type Object. There is no guarentee are runtime as to what exacty type of object will be used, therefore there was no alternative to this sort of implementation.

3.1 Constructors

public ListRuntimeXML()

public ListRuntimeXML(string strXML, List<Object> oList)

The first constructor is a standard default contstructor. If you wish to populate your List from an XML document, and you have some instance of a list or ListXML object that is the target for population, the latter of the 2 suits this purpose.

strXML

This is the XML document describing your object, and all it's public properties as a string.

oList

This is a List class. Since classes are passed by reference vs. value in .NET, an empty instance can be passed in.

3.2. CreateFromXML

There are 2 different overloaded types within the base class.

virtual public void CreateFromXML(string strXML, List<Object> oList)

virtual public void CreateFromXML(string strXML, List<Object> oList, Dictionary<object, object> Objects)

These methods live within the ListXML base class. They populate an instance of an object that inherits this class from the XML that you pass to it, the type, and if there are other user defined types nested within your object, you need to use the latter of the two.

strXML

This is the XML document describing your object, and all it's public properties as a string.

oList

This is an array list that you want to pass in, or it can be a type of ListXML class. Array list inherits from the List class, so you can pass that in since the base type matches the interface argument.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 3.2-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive", new TestObject.TestRecursive());

oListXML = new XML_Utilities.ListXML();

strXMLDoc = oListXML.Load(Application.StartupPath + "\\Test Typed List.xml");

oListXML.CreateFromXML(strXMLDoc,oListXML, oObjects);

oListXML.SaveXML(Application.StartupPath + "\\Test Typed List from file.xml", oListXML.CreateXML(oListXML, oObjects));

//Save the file as XML

oListXML = null;

Fig 3.2-2

This illustrates how to use the CreateFromXML method. The XML is obtained by loading a file, and the resulting string is passed into the argument. The object oArrayXML is then populated based on the data passed into it.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

3.3. CreateXML

virtual public string CreateXML(List<Object> oList)

virtual public string CreateXML(List<Object> oList, Dictionary<object, object> Objects)

This creates an XML document that describes your object at runtime. Your custom object will dynamically discover it's own properties at runtime and obtain information as to the property name, type, and value.

The first declaration is for primitives, and the second is for objects that have other user defined types within them.

oList

This is an array list that you want to pass in, or it can be a type of ListXML class. List inherits from the List class, so you can pass that in since the base type matches the interface argument.

Objects

In the event that you have other user defined or non-primative types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 3.3-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

string strXMLDoc = oListXML.CreateXML(oListXML,oObjects);

Fig 3.3-2

This illustrates how to create the XML from a custom object at runtime. The result is returned to strXML as a string. The string has the XML that explicitly describes the object.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

3.4. Load

virtual public string Load(string strFileName)

This loads an XML document, reads the entire file, and returns a string representation of the XML within the document. You must provide the complete file path as well as the file name for strFileName.

If your file is invalid, or doesn't exist, an exception will be thrown. The inner workings of this function uses a file stream reader object.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oListXML = new XML_Utilities.ListXML();

strXMLDoc = oListXML.Load(Application.StartupPath + "\\Test Typed List.xml");

oListXML.CreateFromXML(strXMLDoc,oListXML, oObjects);

oListXML.SaveXML(Application.StartupPath + "\\Test Typed List from file.xml", oListXML.CreateXML(oListXML, oObjects));

//Save the file as XML

oListXML = null;

Fig 3.4-1

This illustrates how to load an XML file using the Load function. The file is read, and it returns a string representaiton of the XML descibing a user defined object. The XML can then be used and manipulated to populate the object using the CreateFromXML method.

NOTE:

• This does not validate the format of your XML. This function merely loads the file and reads it if it in fact exists. If you wish to validate your XML, there are other means to do that with, or you can implement your own custom XML validator if you wish.

3.5. SaveXML

virtual public void SaveXML(string strFileName, string strXMLDoc)

virtual public void SaveXML(Type t, Object o,string strFileName)

These methods save XML files that explicitly describe your document. Each overloaded declaration works differently from the next one.

If you have a copy of the XML string that describes your object, you can pass that in along with a file name. The file name should include the complete path of your file as well as the filename itself. This uses a stream writer object when invoked to create the XML file.

NOTES:

• If you do not have a string that represents the XML describing your custom object, then you should use the second function. If you do not know what the XML is at runtime, and you are not using anything besides primative data types, use this function.

• However, if you are using custom objects within your root custom object, or anything that deals with nested custom objects, DO NOT USE THE SECOND FUNCTION.

The second function makes an internal call to the CreateXML function for an object of type t, from instance o. It then takes that XML, and passes it to the first function to save it to a file. There is no support for a function to serialize XML to a file whose XML is not known, and who's object has other user defined objects within it. Future versions or releases may support this. Therefore, it is suggested to use the first function if possible.

t

T is the type of object you want to populate. You can obtain this by using the GetType method of a given object. GetType returns a System.Type object, which is what this function uses.

Type Example

SaveXML(typeof(MyObject), m_object,strFileName);

SaveXML(m_object.GetType(), m_object,strFileName);

You can use either typeof([Object_Name]) or [Object_Name].GetType() to obtain a System.Type object for use in this method.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 3.5-1

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oListXML = new XML_Utilities.ListXML();

strXMLDoc = oListXML.Load(Application.StartupPath + "\\Test Typed List.xml");

oListXML.CreateFromXML(strXMLDoc,oListXML, oObjects);

oListXML.SaveXML(Application.StartupPath + "\\Test Typed List from file.xml", oListXML.CreateXML(oListXML, oObjects));

//Save the file as XML

oListXML = null;

Fig 3.5-2

The above illustration demonstrates how to create an XML document using the CreateXML method. From there, you pass that string into the SaveXML method. The complete path is determined dynamically at runtime and concatenated with the actual file name.

4.0 Functions and methods within the DictionaryRuntimeXML Class.

This class is derived in part from Dictionary. Dictionary is parent object from which objects within this class originate from.

4.1 Constructors

public DictionaryRuntimeXML ()

public DictionaryRuntimeXML (string strXML, Dictionary<Object, Object> oDictonary)

The first constructor is a standard default contstructor. If you wish to populate your List from an XML document, and you have some instance of a list or ListXML object that is the target for population, the latter of the 2 suits this purpose.

strXML

This is the XML document describing your object, and all it's public properties as a string.

oDictonary

This is a Dictionary class. Since classes are passed by reference vs. value in .NET, an empty instance can be passed in to this constructor.

4.2. CreateFromXML

There are 3 different overloaded types within the base class.

virtual public void CreateFromXML(string strXML, Dictionary<Object,Object> oDictonary)

virtual public void CreateFromXML(string strXML, ref Dictionary<Object, Object> oDictonary, Dictionary<Object,Object> Objects)

*virtual public void CreateFromXML(string strXML, Dictionary<Object, Object> oDictonary, bool bUDT)

These methods live within the DictionaryXML base class. They populate an instance of an object that inherits this class from the XML that you pass to it, the type, and if there are other user defined types nested within your object, you need to use the latter of the two.

If you are using any user defined types at all anywhere within your object, or a tree if you're nesting user types, you need to explicitly pass a reference of your DictionaryXML object by reference. The reason for this is because it is the only means to force things to update internally, and they need a reference to an instance of your custom object as opposed to an instance.

strXML

This is the XML document describing your object, and all it's public properties as a string.

oDictonary

This is a Dictionary class. Since classes are passed by reference vs. value in .NET, an empty instance can be passed in to this method.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 4.2-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

*bUDT

This is for use for the 3^rd function only. This is for cases in which you have user defined types within your DictionaryXML object, and your DictionaryXML object happens to be nested. This lives in the DictionaryXML class as opposed to the DictionaryRuntimeXML class. It is public, but it lives in the base of DictionaryRuntimeXML.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive", new TestObject.TestRecursive());

oDictionaryXML = new XML_Utilities.DictonaryXML();

strDictionaryXML = oDictionaryXML.Load(Application.StartupPath + "\\Test dictionary.xml");

oDictionaryXML.CreateFromXML(strDictionaryXML, oObjects,true);

Fig 4.2-2

This illustrates how to use the CreateFromXML method. The XML is obtained by loading a file, and the resulting string is passed into the argument. The object oDictionaryXML is then populated based on the data passed into it.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

4.3. CreateXML

virtual public string CreateXML(Dictionary<Object, Object> oDictionary) virtual public string CreateXML(Dictionary<Object,Object> oDictionary, Dictionary<object, object> Objects)

This creates an XML document that describes your object at runtime. Your custom object will dynamically discover it's own properties at runtime and obtain information as to the property name, type, and value.

The first declaration is for primitives, and the second is for objects that have other user defined types within them.

oDictionary

This is an array list that you want to pass in, or it can be a type of DictionaryXML class. Array list inherits from the Dictionary class, so you can pass that in since the base type matches the interface argument.

Objects

In the event that you have other user defined or non-primative types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 3.3-1

The code in the above figure illustrates how you should create the dictionary object to pass in. The dictionary should only consist of user defined types that inherit a base class defined in the XML Object API. The first argument should be the fully qualified name as a string, and the value should be some instance of the object that the API might encounter at runtime.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive", new TestObject.TestRecursive());

strDictionaryXML = oDictionaryXML.CreateXML(oDictionaryXML, oObjects);

oDictionaryXML = null;

Fig 4.3-2

This illustrates how to create the XML from a custom object at runtime. The result is returned to strXML as a string. The string has the XML that explicitly describes the object.

NOTES:

• You do not have to add primitive types to the dictionary, and it is recommended that you do not do this as it will degrade performance at the very least. Primatives that live in the system namespace that are derived from ANSI types do not need to be added to the dictionary. Only custom implementations of objects need to be passed in.

• If you forget to add an object to the dictionary, the XML created will be incorrect, and you will get a runtime exception when you try to populate an object from it.

• Whatever object you add to the dictionary should have a base class of RuntimeXML, ArrayListXML, ListXML, or DictionaryXML. If it does not, you will have a runtime exception thrown because the API doesn't understand it, nor can it dynamically discover the properties that it has at runtime.

4.4. Load

virtual public string Load(string strFileName)

This loads an XML document, reads the entire file, and returns a string representation of the XML within the document. You must provide the complete file path as well as the file name for strFileName.

If your file is invalid, or doesn't exist, an exception will be thrown. The inner workings of this function uses a file stream reader object.

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDictionaryXML = new XML_Utilities.DictonaryXML();

strDictionaryXML = oDictionaryXML.Load(Application.StartupPath + "\\Test dictionary.xml");

oDictionaryXML.CreateFromXML(strDictionaryXML, oObjects,true);

Fig 4.4-1

This illustrates how to load an XML file using the Load function. The file is read, and it returns a string representaiton of the XML descibing a user defined object. The XML can then be used and manipulated to populate the object using the CreateFromXML method.

NOTE:

• This does not validate the format of your XML. This function merely loads the file and reads it if it in fact exists. If you wish to validate your XML, there are other means to do that with, or you can implement your own custom XML validator if you wish.

4.5. SaveXML

virtual public void SaveXML(string strFileName, string strXMLDoc)

virtual public void SaveXML(Type t, Object o,string strFileName)

These methods save XML files that explicitly describe your document. Each overloaded declaration works differently from the next one.

If you have a copy of the XML string that describes your object, you can pass that in along with a file name. The file name should include the complete path of your file as well as the filename itself. This uses a stream writer object when invoked to create the XML file.

NOTES:

• If you do not have a string that represents the XML describing your custom object, then you should use the second function. If you do not know what the XML is at runtime, and you are not using anything besides primative data types, use this function.

• However, if you are using custom objects within your root custom object, or anything that deals with nested custom objects, DO NOT USE THE SECOND FUNCTION.

The second function makes an internal call to the CreateXML function for an object of type t, from instance o. It then takes that XML, and passes it to the first function to save it to a file. There is no support for a function to serialize XML to a file whose XML is not known, and who's object has other user defined objects within it. Future versions or releases may support this. Therefore, it is suggested to use the first function if possible.

t

T is the type of object you want to populate. You can obtain this by using the GetType method of a given object. GetType returns a System.Type object, which is what this function uses.

Type Example

SaveXML(typeof(MyObject), m_object,strFileName);

SaveXML(m_object.GetType(), m_object,strFileName);

You can use either typeof([Object_Name]) or [Object_Name].GetType() to obtain a System.Type object for use in this method.

Objects

In the event that you have other user defined or non-primitive types of objects nested in your code, you need to pass in a dictionary collection of those types of objects. The XML Object API doesn't know what type of object it will need to create and does not understand ProgID's like COM does. It does understand fully qualified names, and it can use references to certain objects.

When passing in a dictionary object, the name of the object should be a string type, and an instance of an object for reference by the API.

Objects Example

Dictionary<object, object> oDict = new Dictionary<object, object>();

oDict.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDict.Add("TestObject.MyObject", new TestObject.MyObject());

oDict.Add("TestObject.TestWidget", new TestObject.TestWidget());

Fig 3.5-1

Usage Example

Dictionary<object, object> oObjects = new Dictionary<object, object>();

oObjects.Add("TestObject.MyObject", new TestObject.MyObject());

oObjects.Add("TestObject.TestRecursive",new TestObject.TestRecursive());

oDictionaryXML = new XML_Utilities.DictonaryXML();

strDictionaryXML = oDictionaryXML.Load(Application.StartupPath + "\\Test dictionary.xml");

oDictionaryXML.CreateFromXML(strDictionaryXML, oObjects,true);

oDictionaryXML.SaveXML(Application.StartupPath + "\\Test Test dictionary from file.xml", oDictionaryXML.CreateXML(oDictionaryXML, oObjects));

//Save the file as XML

oTest.SaveXML(Application.StartupPath + "\\Test dictionary.xml", strDictionaryXML);

oDictionaryXML = null;

Fig 4.5-2

The above illustration demonstrates how to create an XML document using the CreateXML method. From there, you pass that string into the SaveXML method. The complete path is determined dynamically at runtime and concatenated with the actual file name.