********************************************************************** * * * Changes: * * -------- * * * * - 2005-09-12: Initial version (JLE). * * - 2005-09-29: add an explanation to determine the JAXB ver (JLE). * * - 2005-10-11: add details about schema and java classes * * writing (JLE). * * - 2006-03-09: modify the compilation step to take the * * bindGivenScenarioSchema ANT task into account (JLE). * * - 2006-03-09: add the fourth step (JLE). * * - 2008-02-07: Adding information (description, structure) * * (GMO and SBA). * * * ********************************************************************** How to create new scenario events ? =================================== Description of TOTEM scenario file ---------------------------------- Scenario files are XML files. An XML schema has been written and describes the various events and their options that can appear in an XML scenario file. From this schema we have generated java classes using JAXB. Each java class corresponds to one event. When an XML scenario file is executed in the toolbox, each event of the file is instanciated in its corresponding java object and then the TOTEM software calls sequentially the execute method of each object, respecting the order of the scenario file. If you want to add a new scenario event in the TOTEM toolbox the following steps are required. First step ---------- The first step is to write a new XML scenario schema or to modify an existing one. The reader should be familiar with XML Schema and JAXB. If it's not the case, the following links will be helpful: - http://www.w3.org/TR/xmlschema-0/ - http://www.w3schools.com/schema/default.asp - http://java.sun.com/webservices/docs/1.4/tutorial/doc/index.html The normative documents of XML schema are: - http://www.w3.org/TR/xmlschema-1/ - http://www.w3.org/TR/xmlschema-2/ The JAXB API is available here: - http://java.sun.com/webservices/docs/1.4/api/index.html (the JAXB package is javax.xml.bind) The C-BGP scenario schema can be an example of how to write a correct new scenario schema. It is located in src/resources/scenario. There are some constraints when writing the XML schema: 1. The events you defined must inherit from one of the following events defined in the general scenario schema (located in src/resources/scenario/Scenario-v1_x.xsd): - eventType (general event type) - ASEventType (intra-domain events, they must have an AS ID) - TMEventType (traffic-related events, they must have a TM ID) - ASTMEventType (intra-domain traffic-related events, they must have an AS ID and a TM ID). Moreover, they must belong to the "event" substitutionGroup. It gives the following body for an user-defined event: * attributes and/or sub-elements specific for this event - this section can be empty * 2. The XML namespace of the schema must have a special value. Indeed, the XML namespace has a special meaning in TOTEM: we use the XML namespace to retrieve the package where the events are implemented. You must define the namespace such that when reversing it we obtain the package where the JAXB classes will be generated. Example: namespace = http://jaxb.model.scenario.mysite.com --> package = com.mysite.scenario.model.jaxb For your information, in the parent package (com.mysite.scenario.model) you will later write one class per new event (see step 4). Second step ----------- Once the schema has been modified or a new schema has been written, the second step is the compilation of the schema. This will create the JAXB generated classes. - If you have created a new schema, you can use the bindGivenScenarioSchema ANT task to do that. To use this task, you can execute the following ANT task: ant -Dschema=*path_to_schema* -Dschema.jaxb.dir=*dir_for_JAXB_classes* bindGivenScenarioSchema The "schema" property must contain the path to the XML schema (*path_to_schema*) to compile (without the ".xsd" extension). A JAXB bindings file must exist for the schema in the directory corresponding to this path. It MUST have the same name as the schema followed by "-bindings.xjb". The "schema.jaxb.dir" property must contain the relative directory where the JAXB classes will be generated (*dir_for_JAXB_classes*), e.g. /com/mysite/scenario/model/jaxb. This directory MUST correspond to the package given in the JAXB bindings file corresponding to the schema. - If you added new events to the actual base schema (src/resources/scenario/ Scenario-v1_x.xsd) rather than creating a new one, you can simply add the bindings correponding to the new events to the file Scenario-v1_x-bindings.xjb and then execute the following ANT task: ant bindScenarioSchema Third and fourth step --------------------- The third step is to modify (if needed) the preferences.xml file which is in src/resources. You must modify the two keys SCENARIO-PACKAGES and SCENARIO-SCHEMA-LOCATION. This way, the TOTEM application can access to the schema while running. The fourth step is to write and implement the classes containing the code of the events (the classes in package com.mysite.scenario.model). You will have to write a class for each new event - whose name corresponds to the name of the scenario event (except the first letter which can be a lowercase in the event name and a uppercase in the class name) - that extends the corresponding generated JAXB class (in com.mysite.scenario.model.jaxb.impl) - that implements the Event interface (in be.ac.ulg.montefiore.run.totem.scenario.model) As this new class implements the Event interface, it also has to contain the "action()" method which defines the behaviour of the event. This is the method called when the event is executed. Finally if you want to include your algorithm in the publicly available version of the toolbox, you will have to put the new scenario file on the TOTEM website. For this step you can contact the current TOTEM developers. Let's now give an example of the resulting structure in the Java code. If you defined an event "myEvent" in the namespace "http://jaxb.model.scenario.mysite.com", you should obtain the following structure : com.mysite.scenario.model | |- Classes implementing the events. In our case, we should have a | class MyEvent implementing the Event interface and extending | com.mysite.scenario.model.jaxb.impl.MyEventImpl (this is the | class generated by JAXB). | |- Package jaxb (e.g. com.mysite.scenario.model.jaxb) which contains the interfaces generated by JAXB. | |- Package impl (com.mysite.scenario.model.jaxb.impl) which contains the classes implementing the preceding interfaces. These classes are also generated by JAXB. Remarks ------- Note that when you write a scenario file, you have to use namespaces. If you need an example, see the examples/abilene/Scenario/bgp-scenario1.xml file in the TOTEM archive. The user guide also gives some explanations to do that. -- Jean Lepropre (lepropre@run.montefiore.ulg.ac.be) (2005-2006) -- Gael Monfort and Simon Balon (feb. 2008)