Last edited: 5 May 2004

by Thor List,

CoreLibrary XML Specification Document



Table of Contents


Introduction. 1

The Object Class. 1

The Basic API 2

The Convenient Tools. 3

The String Class. 3

The Collection Classes. 4

OrderedCollection. 4

OrderedObjectCollection. 4

Dictionary. 5

ObjectDictionary. 5

The Time Class. 5

The Message Class. 6

The TCPLocation Class. 7

Alphabetical List of Objects. 7





            The CoreLibrary is an OpenSource project on and is intended for C++ to be what the basic object classes are for Java. Every object is an Object and inherits a standard API from the Object class, such as print(), toXML(), fromXML(), wait(), and many more.


There are a great number of classes available from the CoreLibrary and this number is expected to grow as the project is used by more and more people. It contains most of the basic useful objects already, such as Strings, Times, Collections, Threads (Win32/Linux/Unix/MacOSX), Semaphores, Mutexes and an advanced set of networking classes for acting both as client and server for any number of protocols including acting as a web server and telnet server.


See the Alphabetical List of Objects  7 at the end of this document.


The Object Class


            The common base of the CoreLibrary is the Object object, as in Java. This object is never meant to be instantiated on its own, but only exists to provide a common base API so that every object in the CoreLibrary can be referenced as ‘an Object’.


The API of all Objects is as follows:


    virtual ~Object();
                                                JString createUniqueID();
    virtual bool unitTest();                    void addUnitTestLog(JString str);
    virtual bool equals(Object* o2);            JString getUnitTestLog();
    virtual JString print();                    virtual JString getClass();
    virtual JString toXML();                    int getProcID();
    virtual bool fromXML(JString xml);          bool wait(long ms);
    virtual bool fromXML(XMLNode* node);        Object* createObjectFromXML(JString& xml);
    virtual Object* clone() = 0;                Object* createObjectFromXML(XMLNode* node);    

The constructor and destructor takes no argument and never need to be called directly or indirectly.


The API is split into two groups, namely a Basic API intended to be overwritten by new object types (the left column above), and a set of useful tool functions to be accessed for convenience (the right column above).


The Basic API


In no particular order the API to be overwritten is as follows:


    bool unitTest();                A Boolean function to test the internals of the Object

                              Example for a String is to test that all its functions

                              return the expected result, one by one.

    bool equals(Object* o2);        Implement equals for Objects, defaults to checking the

                              pointer of the Object

    JString print();                A standard human readable string

    JString toXML();                Convert the Object into a reversible XML representation

    bool fromXML(XMLNode* node);    Reinitialize the Object back from the XML representation

    bool fromXML(JString xml);      Take a string, parse it as XML and call fromXML(XMLNode*)


    Object* clone() = 0;            Return an instantiated copy clone of an Object

                                    NB: This function must be overwritten

The Convenient Tools


    bool wait(long ms);                   A standard sleep function

    JString createUniqueID();             Create a unique random string ID

    void addUnitTestLog(JString str);     Add a print string during UnitTesting, to be accessed

                                          mainly if unitTest() returns false

    JString getUnitTestLog();             Gets the above print string

    JString getClass();                   Returns the class name, such as “JString”, “Time”, etc.

    int getProcID();                      Returns the OS process ID number

    createObjectFromXML(JString& xml);    Parses the XML string and calls the function below

    createObjectFromXML(XMLNode* node);   This function will take any XML and try to recreate

                                          an instantiated version/copy of the Object which

                                          generated the XML. It will work automatically with

                                          most Objects in the CoreLibrary. Please see the files

                                          AutoXML.code and AutoXML.cheader for more details.



The String Class


            The JString class in the CoreLibrary is a basic string representation class with a full set of string manipulation functions. It itself is used to hold unparsed XML, of course, but can also be converted from and to XML.


The generic XML 1.0 expression of a String is:


    <string>Some Text</string>


but if embedded into another object such as a Collection it is often represented without the <string> tag as bare text.


The CollectionBase Classes


            The CollectionBase class is a subclass of four types of Collections. These are the Collection (an ordered collection of Strings, an extendable array of strings), the Dictionary (any string key matching any string value, such as “key” = “value”), the ObjectCollection (an ordered collection of Objects, just as the strings above) and finally the ObjectDictionary (any string key matching any Object value, such as “key” = Object*).




The Collection is merely a collection of Strings.


The generic XML 1.0 expression of an Collection is:







The ObjectCollection is a collection of Objects.


The generic XML 1.0 expression of an ObjectCollection is:


            <time sec="1064500814" ms="48" text="Thu Sep 25 2003 15:40:14:048" />
            <time sec="1064500814" ms="48" text="Thu Sep 25 2003 15:40:14:048" />




The Dictionary has a unique key for each entry.


The generic XML 1.0 expression of a Dictionary is:


        <entry name="key1">10252023.62</entry>
        <entry name="key2">13504900.27</entry>

    </ dictionary >




The ObjectDictionary has a unique key for each Object entry.


The generic XML 1.0 expression of an ObjectDictionary is:


        <object name="key1">
            <time sec="1064500814" ms="48" text="Thu Sep 25 2003 15:40:14:048" />
        <object name="key2">
            <time sec="1064500814" ms="48" text="Thu Sep 25 2003 15:40:14:048" />
    </objectdictionary >


The Time Class


            The Time class contains the current date and time down to the millisecond accuracy. Additionally, you can compare two times created in the same executable down to 1 microsecond resolution on Linux and 100 nanosecond resolution in Win32.


The generic XML 1.0 expression of a Time is:


    <time sec="1064500814" ms="48" text="Thu Sep 25 2003 15:40:14:048" />


where the text field is for human readability as well as a check after the Time object has been re-instantiated from XML to see if the current Time object generates the same text string. This class has an additional ability to change the tag name to any text string, as seen in the Message class below:


    <postedTime sec="1068741023" ms="589" text="Thu Nov 13 2003 16:30:23:589" />


This is achieved with the call toXML(“tag”) and the parsing of this back into a Time Object is completely automatic.


The Message Class


The Message class contains a list of entries with a few fields required:


v     priority              a floating point number

v     type                  the type of the message as text

v     timeout              a floating point number in ms

v     id                      a unique identifier in UUID format

v     from                  the sender/originator of the message

v     to                      the intended receiver of the message

v     cc                     the intended carbon copy receivers: a;b;c

v     extensions         a text field for description of extensions

v     comment           a comment field

v     stored               where is this message stored

v     postedTime       the creation and initial posting time of the message

v     receivedTime    when was this message received by receiver

v     content              the text content of the message

v     language            the language of the text content


The generic XML 1.0 expression of a Message is:


        <createdTime sec="1068741023" ms="590" text="Thu Nov 13 2003 16:30:23:590" />
        <postedTime sec="1068741023" ms="590" text="Thu Nov 13 2003 16:30:23:590" />
        <receivedTime sec="1068741023" ms="590" text="Thu Nov 13 2003 16:30:23:590" />
        <content language="xml">




Any additional field can be added at will, much like a voluntary dictionary, but can never be required. Often, the content will be xml, but can equally well be any other language, but should then be HTML/URL encoded (see RFC2396), so not to confuse the XML parser, meaning all non-allowed characters such as ‘<’, ‘>’, etc. should be replaced with ‘&#60;’, ‘&#62;’, etc.


The TCPLocation Class


            The TCPLocation class contains a TCP/IP address along with several other pieces of information, such as name of module located there, the OS process ID, the IP number if resolved, the pointer to an Object if needed and a protocol name such as HTTP.


The generic XML 1.0 expression of a TCPLocation is:


    <tcplocation address="" port="1234" name="MyName" procid="123456" ipnumber="" pointer="44784" netprotocol="HTTP" />








Alphabetical List of Objects


This is a list of all objects in this document, sorted alphabetically and called by their actual names, i.e. the C++ class name, corresponding to the file names of their class definition (name.h) and the class implementation (name.cpp).