/*

 * Copyright (c) 2002-2003 IST-2004-2006-511731 ModelWare - ModelBus.

 * All rights reserved.

 *

 * This software is published under the terms of the ModelBus Software License

 * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even

 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

 * A copy of ModelBus Software License is provided with this distribution in

 * doc/LICENSE.txt file.

 */

---------------------------------------------------

MODELBUS TOOLKIT README

---------------------------------------------------

What is ModelBus Toolkit ?



*ModelBus Toolkit is an application for creating specific

adapters and stubs for your modeling service tool, to allow it to

interoperate with other modeling service tools through ModelBus.



*ModelBus Toolkit uses a description file to generate specific 

adapters and stubs necessary for the modeling service tool described.
This file or description may be created thanks to EMF using the 
modelbus description ecore.

It checks that the description model is valid before attempting to

generate the specific adapters and stubs.


Modelbus Toolkit installation :
-------------------------------------


Modelbus Toolkit needs : 

	-ModelBus Adapter 

	-ModelBus Description
	
	-ModelBus Description Edit and Editor

	-EMF common

	-EMF ecore

	-and EMF ecore xmi 

on its build path when building from source. 



How to use ModelBus Toolkit ?
---------------------------------------

*One can start toolkit functionalities from the tool description editor.
When editing tool description, right-click on a description element and choose ModelBus Toolkit item in the context menu.
The following options are available:
- Description Validation
- Stub/Skeleton Generation 


*You may start ModelBus Toolkit by typing the shell/ MSDos command :

java org.eclipse.mddi.modelbus.toolkit.ToolKit tool_description_file [-options]


where tool_description_file is the absolut path of the model file of the tool for which 

the adapters and stubs must be generated.  


where [-options] can be :

-directory directory_path       to specify the output directory for the generated files

-package package_name        to specify the package for the generated files

-help				to print the usage of the command



How must the description file be formatted ?
------------------------------------------------------


* You may create a description file using EMF (Eclipse project) and the Modelbus
description.ecore : charge the ecore into EMF and create a new description model.

* You may create "manually" a description file : it is an xmi version 2 file.
Its main node is a special ModelBusPackaging node. This main node must contain 
excactly one Tool node (see below for further information)
For example :

<tooldescription:ModelBusPackaging xmi:version="2.0" 
xmlns:xmi="http://www.omg.org/XMI" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:abstract="http://modelbus/description/abstract" 
xmlns:concrete="http://modelbus/description/concrete" 
xmlns:tooldescription="http://modelbus/description">

 //the description of your tool

<content xsi:type="concrete:Tool" name="toolname" interface="//@content.0" platform=""/>
</tooldescription:ModelBusPackaging>



NB : xmi referencement rules 
------------------------------------


eventInfo="//@content.4" means that the type referenced by eventInfo 
is the Type specified by the fifth child of the main node

eventInfo="//@content.0/@content.4" means that the type referenced by 
eventInfo is the Type specified by the fifth child of the first child of the main node.

eventInfo="//@content.0 //@content.4" means that the types referenced 
by eventInfo are the Types specified by the fifth and first child of the main node



Node description :
----------------------


- EventType nodes have a name (cf. "Name constraints" below) and a type. For example : 
<content xsi:type="abstract:Event" name="eventName" 
eventInfo="//@content.0 //@content.4"/> 
// eventInfo references the type(s) of the Event 
// (eventInfo is the only attribute to allow multiple type)

  
- Error nodes have a name (cf. "Name constraints" below) and a type and 
can have upper and lower bounds (cf. "Lower and Upper constraints" below). For Example :

//with bounds
< serviceError name="errorName" type="//@content.3" upper="-1" lower="1"/>
// without bounds
<serviceError name="errorName" type="//@content.3"/>  
// for now, default bounds are lower 1, upper 1 (cf. ModelBus metamodel)


- ModelBusPackaging nodes have a name (cf. "Name constraints" below), 
and can contain ModelBusPackaging nodes, ModelingServiceInterface nodes, 
Event nodes and Type nodes (PrimitiveTypes or ModelTypes). 
At least one ModelBusPackaging must contain a ModelinServiceInterface. 
For example:

<content xsi:type="tooldescription:ModelBusPackaging" name="ServicePackage">
//contents of package (ModelingServiceInterface, Type, ModelbusPackaging, Event)
</content>


- ModelingServiceInterface nodes have a name (cf. "Name constraints" below), 
and can contain ModelingService nodes and/or reference EventType nodes 
(referenced by the publishedEvent attribute). For example :

<content xsi:type="abstract:ModelingServiceInterface" name="msi1" 
 publishedEvent="//@content.2 //@content.3"> //msi1 references two Events
//contents of interface (i.e ModelingServices)
</content>


- ModelingService nodes have a name (cf. "Name constraints" below) and a type, 
and can contain Parameter nodes (one at least, according to ModelBus metamodel) 
and Error nodes. For example :

<service name="serviceName">  //ModelingService node
//contents of service ( parameters, errors)
</service>


- Parameter nodes have a name and type, optionally you may specify parameter direction 
( the options are "in", "out", "inout", default is "in"), 
and upper and lower bounds (cf. "Lower and Upper constraints") for the parameter. 

//without direction and upper and lower bounds
<parameter name="param1" type="//@content.2"/>

// with direction
<parameter name="param2" type="//@content.3" direction="out"/>

// with upper and lower bounds
<parameter name="param2" type="//@content.3" upper="1" lower="0"/>


- Property nodes have a name (cf. "Name constraints" below) and a value,
 expressed as strings. For example :

<property name="URL" value="http://localhost:8081/testTool"/>

Property names are : 
Session (possible values : true, false), 
Communication (synchronous, asynchronous), 
Identification (true, false), 
ModelEncoding (XMI2.0, XMI2.1, EMF2.1). 


- Tool node has a name (cf. "Name constraints" below), 
an interface and optionally a platform attribute and Property nodes. For example :

<content xsi:type="concrete:Tool" name="testTool" interface="//@content.0" platform="">
    	//contents of Tool properties if needed
<property name="URL" value="http://localhost:8081/testTool"/>
<property name="Session" value="true"/>
</content>


- MetaclassSpecification nodes have a name (cf. "Name constraints" below) 
and can have upper and lower bounds (cf. "Lower and Upper constraints" below). 
For example :

//with bounds
<content name="metaClassName" upper="-1" lower="1"/>

// without bounds
<content name="metaS1"/> 
// for now, default bounds are lower 0, upper 0 (cf. ModelBus metamodel)


- Type nodes (either PrimitiveType or ModelType) have a name, 
and if they are ModelType nodes can have MetaclassSpecification nodes. For example :

// names of primitive type nodes must be "boolean", "double", "integer" or "string" 
<content xsi:type="abstract:PrimitiveType" name="string"/> 
//model type nodes
<content xsi:type="abstract:ModelType" name="modelTypeName">
//contents of ModelType if needed
<content name="metaClassName" upper="-1" lower="1"/>
<content name="metaClassName2" upper="1" lower="1"/>
...
</content>
 

Lower and Upper constraints :
------------------------------------

Lower and upper attributes must respect following rules:
- lower and upper are integer
- lower >= 0
- upper >0 or upper = -1 ( for infinity)
- lower <= upper

Lower and upper attributes have default values. 
But these default values are able to change (depending from the ModelBus metamodel), 
so be aware of error message when generating an adapter.

Name constraints :
----------------------

Some attribute of the tool description must repect these rules, according to Java code:
A name must only contains these characters
- a-z
- A-Z
- 0-9 ( except for the first character)
- _
- $
- and the name must not correspond to a Java reserved keywords, and must not be empty.
