testing.html

/**

@page Testing Testing
The following pages contain tests for our framework.

- @subpage TestConnect
- @subpage TestConnectComplex
- @subpage TestConnectMultiple
- @subpage TestConstruct
- @subpage TestUpdate
- @subpage TestAction
- @subpage TestDestruct
- @subpage TestPlugin
- @subpage TestPluginChain
- @subpage TestPointer
- @subpage TestPointerUnres
- @subpage TestPointerUnset
- @subpage TestPointerChange
- @subpage TestReadObj







@page TestConnect 1. Connection (simple)
The following test will just test connection from a client to a server.

@section ClientApplication Client Application
The following code shows a very simple client, the client just initiates its connection to a given host on port 8000 and displays when ClientFramework::onConnect() is called.
@include testing/1_connection/client_main.cpp

@section ServerApplication Server Application
The following is the server for this test, it is also very simple. It just listenes on port 8000 and then print when clients connect and disconnect.
@include testing/1_connection/server_main.cpp







@page TestConnectComplex 2. Connection (complex: use handshaking)
This test will send along data during the handshaking/connection phase, to validate the client. The following things will be tested:
- %Client sends a username using ClientFramework::writeHandshakeInitMessage(FrameworkPacket * fp)
   - Server accepts it
   - Server rejects it
- Server sends a version number using ServerFramework::onInitialHandshake(FrameworkPacket * handshake, FrameworkPacket * reply)
   - %Client accepts it
   - %Client rejects it

@section ClientApplication Client Application
The following code shows a very simple client, the client just initiates its connection to a given host and sends a username along. If it receives a discontinue packet it prints out a reason sent by the server. If it receives a continue-packet it checks a version string sent by the server with its own version string and either sends a continue-packet or a discontinue packet.
@include testing/2_handshaking/client_main.cpp

@section ServerApplication Server Application
The following is the server for this test, it is rather simple. It checks the username sent by the server, anf if it matches it sends a continue packet with its version string. If it does not match it sends a discontinue-packet.
@include testing/2_handshaking/server_main.cpp





@page TestConnectMultiple 3. Multiple clients connecting
This test will have multiple clients connecting and handshaking at the same time, the source for this test is the same as for test @ref TestConnectComplex, we just start multiple clients to see that everything works as expected.









@page TestConstruct 4. Construction of objects
This test will set up a ServerData object on the server and then call ServerData::sendCreateObjectToAll(). The client will have set up a static method for creating objects of this class using the method:
\code
ClientFramework::registerConstructor(unsigned int class_id, ClientData * (*func)(ClientFramework *, FrameworkPacket *))
\endcode
This method should be called, and a new ClientData object should be created from the FrameworkPacket.

@section ClientApplication Client Application
In this example you should notice the new class MyClientData, which is a subclass of ClientData. This class has a static method that constructs new objects of this class. It is not necessary to place this static method on the class it self, but it makes sense to keep them together.

You should also notice how this "constructor" method is registered in the ClientFramework, the most important thing is the ID with which it is registered, this ID is the same as the server-object uses to specify what "constructor" function to use. Hence they MUST match.

Also you should notice the constructor of MyClientData, it takes the framework and the packet with which it should be constructed as arguments. And after calling its superclasses constructor it reads the values from the supplied ClientPacket.

@include testing/4_constructors/client_main.cpp

@section ServerApplication Server Application
This test-server has like the test-client a datatype MyServerData, and this class is a subclass of ServerData.

The interesting things to notice in this test are the method fillCreateObjectPacket() and getClassId() which are called when the ServerFramework wants to create a constructor packet. The getClassId() MUST match the ID with which the constructor function is registered on the client, and the fillCreateObjectPacket() must fill in all data required for the client-version of this data-type to construct.

The object-ID (as opposed to the Class-ID) of the data (which is the same on the server and client version of the data-entity, you need not worry about, this will be taken care of by the framework).
@include testing/4_constructors/server_main.cpp













@page TestUpdate 5. Update of objects
In this test we will set up a ServerData object on the server, replicate it to the client upon connect using the member-method:
\code
void sendCreateObject( Client * client) const;
\endcode
Then during each pass of the mainLoop on the server, we will change the object and send an update to all connected clients using the member-method:
\code
void sendUpdateToAll(unsigned char type, bool reliable) const;
\endcode
The client will print out the object during each pass of its mainLoop, thus showing the change.

@section ClientApplication Client Application
In this example you should notice the implementation of the member method:
\code
virtual void updatePacket(ClientFramework * f, char updatetype, ClientPacket * packet);
\endcode
This is the method which is called when we receive updates from the server. The updatetype is used to determine which kind of update this is. In this simple test we only use one type, but you can specify any number from 4 to 255. The update-types below 4 are reserved for constructors, destructors, plugins and the framework packets.

@include testing/5_object_updates/client_main.cpp

@section ServerApplication Server Application
There is not much to notice here, we create 3 dataobjects and each pass in the mainLoop we update their position, and send an update to all connected clients. You should notice the member method:
\code
virtual void fillUpdatePacket(ServerPacket * packet, unsigned char type) const;
\endcode
This method is called when ever we need an update packet of a specific type from the object. All this method does in this example is write its coordinates to the packet.

@include testing/5_object_updates/server_main.cpp













@page TestAction 6. Actions sent from Client-object to Server-object
This test will set up a ServerData object on the server, replicate it to the client, and then the client will call the ClientData::updatePacket(ClientFramework * f, char updatetype, FrameworkPacket * packet) method to send an action back the server-version of the object.

@section ClientApplication Client Application
In this example you should notice the implementation of the member method:
\code
MyClientData::sendSomeAction();
\endcode
This is the method that sends an action to the server. The parameters for constructing a packet are described in the source.

@include testing/6_object_actions/client_main.cpp

@section ServerApplication Server Application
This test-server does not do much, it just prints out the actions when they are received. The actions are received in the virtual method:
\code
virtual void clientPacket(Client * client, unsigned char type, ServerPacket * packet);
\endcode

@include testing/6_object_actions/server_main.cpp













@page TestDestruct 7. Destruction of objects
This test will set up a ServerData object on the server, replicate it to the client and then destroy it on the server. This should result in a call to ServerData::sendDestroyToAll() and the client should destroy the object as well.

@section ClientApplication Client Application
There is not much to notice in this client-application. All it does it print out when ever an object is constructed and when ever it is destructed. Every pass in the mainLoop it prints out how many objects are registered in the framework, to make sure that they are also unregistered upon destruction.

@include testing/7_destructors/client_main.cpp

@section ServerApplication Server Application
The server just creates new objects every 5th pass in the mainLoop, and destroys them all again every 27th pass. Before it destroys them, it calls the method:
\code
virtual void sendDestroyObjectToAll();
\endcode
To make sure all connected clients receive word of the object no longer being on the server. You should note however that you can instruct a client to destroy an object even though this object remains on the server, this could be the case if the object for some reason is no longer visible to a specific client.

@include testing/7_destructors/server_main.cpp













@page TestPlugin 8. Plugins (pack/unpack)
In this test we create a plugin that aggregates packets and send one collected packet when purged. This is a good example of the usage of plugins, since it makes sense to sometimes want to aggregate all data to a client into bulks, to minimize overhead.

@section MyTestPlugin Test Plugin
The plugin has both a packing and unpacking side to it. The packing side gets packets in the member method:
\code
Plugin::pack(PacketType * packet);
\endcode
Here it appends the packet to a packet for the given client. If no packet for this client exists it creates one. When the server calls the "purge()" method the plugin wraps up it's packets and sends them along.

On the receiving side the plugin will read the size of the packets, one by one, untill it reads a 0 size packet, this means that there are no more packets, and the readin stops. All this happens in the unpack(...) method.

@include testing/8_plugins/test_plugin.h

@section ClientApplication Client Application
The client application in this example uses the member method:
\code
ClientFramework::registerPlugin(Plugin<ClientPacket> * plugin);
\endcode
to register the plugin. It should be noted that opposed to the server the client does not specify chains of plugins, since every unpacking should result in new packets forwarded back to the inqueue. That way recursively unpacking nested packets.

@include testing/8_plugins/client_main.cpp

@section ServerApplication Server Application
The server in this test creates some objects first. Then when a client connects, it switches the presending chain to use the plugin we have created for the test. Then it sends the client constructor packets for all the data. Finally it purges the presending chain, to let the plugin know that it should send along its aggregated packets. After this it changes back to the default presending chain (the chain where packets are inserted directly into the outqueue).

@include testing/8_plugins/server_main.cpp













@page TestPluginChain 9. Presending chains (multiple pack/unpack)
In this test we will create a chain of plugins on the server, and on the client the nested wrapping should be unpacked correctly.

@section AggrPlugin Aggregation Plugin
The first plugin is the same as in the previous excample, it aggregates packets into one large packet.

@include testing/9_presending_chains/aggr_plugin.h

@section ZlibPlugin ZLIB compression Plugin
The second plugin is a compression plugin using <a href="http://www.zlib.net/">Zlib</a>. This plugin does not need the onPurge(...) method, because it just forwards the compressed data-packet. The combination of these two plugins is smart, since packets are first collected into one large packet and then compressed to minimize bandwidth usage.

@include testing/9_presending_chains/zlib_plugin.h


@section ClientApplication Client Application
The client application is the same as the example before, except this one registeres both plugins.

@include testing/9_presending_chains/client_main.cpp

@section ServerApplication Server Application
The server in this test is almost the same as in the previous test, except the presending chain in this application contains two plugins. We also create a little more objects to better see the impact of the compression.

@include testing/9_presending_chains/server_main.cpp











@page TestPointer 10. Pointer (simple: write - read)
This test will create two ServerData objects on the server, one with a pointer to the other. This is a very small <a href="http://en.wikipedia.org/wiki/Tree_%28graph_theory%29">tree</a>, and the objects are sent to the client bottom up. The client should then be able to look up the object that is pointed to (the pointee) and correctly assign the pointer on the pointing object.

@section ClientApplication Client Application
The client application here just prints out the dataobjects when they are constructed. That way we can see what they are pointing at. You should notice the method called on the packet:
\code
template<class T>
void ClientPacket::readPtr( ClientData * receiver, T ** ptrptr, ClientFramework * framework );
\endcode
This method will be given the object trying to read the pointer, and a pointer-pointer to the pointer its trying to read. The framework is also supplied because the object is being lookup here. If the object cannot be found the pointer will be set to NULL (this is possible because we get a pointer-pointer).

@include testing/10_pointers/client_main.cpp

@section ServerApplication Server Application
The server in this test creates two data objects, and links one of them to the other, then when a client connect, construction packets are sent to the new client in the bottom up order.

You should notice the packet-method:
\code
void writePtr( const ServerData * obj );
\endcode
This call will actually just write the unique ID of the data-object, or 0 if the pointer is NULL.

@include testing/10_pointers/server_main.cpp












@page TestPointerUnres 11. Pointers (cyclic: write - read - resolved)
In this test we will create two ServerData objects, both with a pointer to each other. When we send them to the client, the client should update the first object once the second arrives, thereby resolving the "missing pointer".

@section ClientApplication Client Application
The client application is the same as in the last test.

@include testing/11_pointers_cyclic/client_main.cpp

@section ServerApplication Server Application
The server in this test tells the two objects to point at each other, that is the only thing different from this test and the previous.

@include testing/11_pointers_cyclic/server_main.cpp













@page TestPointerUnset 12. Pointer (complex: write - read - unset)
In this test we set up two ServerData objects, one pointing to the other (the small <a href="http://en.wikipedia.org/wiki/Tree_%28graph_theory%29">tree</a>). We then send them bottom up, for easy resolving the pointer. Then on the server we tell the pointing object to no longer point at the pointee, and send an update to all connected clients.

@section ClientApplication Client Application
The client application is almost the same as in the last test.

@include testing/12_pointers_write_read_unset/client_main.cpp

@section ServerApplication Server Application
The server in this test creates the two objects, one pointing at the other. Then after a while it tells the pointing object to point at nothing. And sends out updates on the change.

@include testing/12_pointers_write_read_unset/server_main.cpp










@page TestPointerChange 13. Pointer (complex: write - read - change)
In this test we do much the same as in the last test, except here we change what the objects are pointing at over time. When ever we change something we send updates to the clients.

@section ClientApplication Client Application
The client application is almost the same as in the last test. Except in this test we print out the PointerPointerTableThingy to make sure that this contains the expected values.

@include testing/13_pointers_write_read_change/client_main.cpp

@section ServerApplication Server Application
The server just flips the pointers around every now and then, and sends out updates about it.

@include testing/13_pointers_write_read_change/server_main.cpp











@page TestReadObj 14. Nested Objects (write/read)
In this test we set up a ServerData object, this object has multiple "children" all with baseclass ServerData. When we create the contruct-packet for the client we write these "children" to the packet also. On the client-side we use the method FrameworkPacket::readObject( ClientFramework * f ) to read and construct these "children".

@section ClientApplication Client Application
In this client application we use 2 datatypes, one that is the child and one that is the parent. What you should notice is the call to:
\code
template<class T>
T * ClientPacket::readObject( ClientFramework * f );
\endcode
This is the method used to read out a "sub-object" from a packet. It should be noted though, that this does NOT have the same posibilities as sending the objects by them selves, and refering them with pointers.

@include testing/14_nested_objects/client_main.cpp

@section ServerApplication Server Application
The server also uses two different datatypes. One as the children, and the other as the parent. Note that even though we are actually sending 4 data-objects we nest them all into one packet.

@include testing/14_nested_objects/server_main.cpp



*/

---