Plug-outs are external programs written in C++ or Java which interact with BOUML via a network socket. These programs may be written using BOUML itself. The previous chapters describe some plug-out including the code generators and code reverse.
A plug-out is a very practical way to automate treatment on the model; do not hesitate to write one. I just recommend you to save your model before executing your plug-outs when you debug them :-) !
If you right-click on any item in the browser tree, you will see a pop-up menu. Select the Tool item and you will see a list of all the plug-outs which can operate on the item you right-clicked.
Additionally, if a plug-out is able to operate at project level (see the Prj column described below), then the plug-out's description will also appear in the Tool menu in the menu-bar at the top of the BOUML window.
To be executed, a plug-out must be declared through the tool dialog called when you select the tools settings entry of the tools menu :
The first column specify how the plug-out is executed, for a C++ program you just have to give its name and may be the path depending on your environment, in Java the -cp option allows to specify the path and the starting class is Main (except if you change the definition of the executable artifact !).
The content of the second column will be displayed in the menu when your plug-out is applicable on the target item.
The other columns allows to specify the kind of the items on whose the plug-out is applicable. The icon in each column header corresponds to all instances of that icon in the browser view (see the browser items page for a summary of the meaning of all icons). If a column in a plug-out row is checked, it means that you can right-click an instance of that icon in the browser view, select the Tool item at the bottom of the pop-up menu, and then initiate the plug-out's operation on the instance you right-clicked.
For instance, in the screenshot above, the row for the gpro executable contains a single X in the column corresponding to the artifact icon. This means that you can right-click any artifact in the browser tree, select Tool then Generate .pro to generate the corresponding .pro file.
As usual the last column do allows to copy/past/cut/insert line and applies on the line where you did the mouse click.
Note that the declaration of the plug-out is saved in the file named tools, this allows you to quickly set the tools list after creating a new project copying the tools file of an old project (this file is read when you load the project).
The distribution of BOUML contains a project named empty, this one is a plug-out doing nothing for you point of view, in fact it implements in C++ and Java the API allowing to interact with BOUML. To develop a new plug-out open the empty project, BOUML will ask you to save it in an other project to keep empty unmodified. You may also develop a plug-out from one of the others available plug-outs, you just have to know that these ones was developed at different step of the BOUML definition, then they do not contain all the BOUML API and some operations may not be defined. By definition, empty contains all the API.
The empty plug-out contains several already defined classes with their associated artifact, half of them are placed under the package API BASE and implement the API with BOUML, you cannot modify them, they define the system part of a plus-out. The other half is yours, each of these user classes inherits to a system class, and sometimes a system class inherits of a user class, for instance the classes associated to ... the classes are:
In this diagram the blue classes are the system classes, the other classes are yours. UmlItem is the user class inherited by almost all the other classes.
The disadvantage of this choice in C++ is to recompile many files when a base class is modified, but this allows to define (virtual) operations managing several classes.
I do not describe in this documentation all the predefined classes and their operations, the better is to look at the model of a newly created plug-out or to generate the html pages describing it (this is done under the empty_html directory, the html entry page is index-withframe.html). I also recommend you to look at the plug-outs given with the BOUML distribution. Nevertheless you have to know :
the entry point of a plug-out in C++ and Java is placed in the artifact named Main under USER API, refer to it
if the C++ pre-processor variables WITHCPP, WITHJAVA, WITHPHP, WITHPYTHON, WITHMYSQL and WITHIDL are defined (using #define or -D option of the G++ compiler, etc ...) you will get all the informations from BOUML.
if the C++ pre-processor variables WITHCPP, WITHJAVA, WITHPHP, WITHPYTHON WITHMYSQL and WITHIDL are not defined you will access only to UML data, this means for instance that the operations cppDecl javaDecl phpDecl and idlDecl will not be defined for UmlBaseClassItem, this limits the amount of data managed by a plug-out and reduce the execution time and used memory space
if only WITHCPP is defined you will access only to UML and C++ data, this means for instance that the operations javaDecl phpDecl mysqlDecl and idlDecl will not be defined for UmlBaseClassItem, this limits the amount of data managed by a plug-out and reduce the execution time and used memory space
if only WITHJAVA is defined you will access only to UML and Java data, this means for instance that the operations cppDecl phpDecl mysqlDecl and idlDecl will not be defined for UmlBaseClassItem, this limits the amount of data managed by a plug-out and reduce the execution time and used memory space
if only WITHPHP is defined you will access only to UML and Php data, this means for instance that the operations cppDecl javaDecl mysqlDecl and idlDecl will not be defined for UmlBaseClassItem, this limits the amount of data managed by a plug-out and reduce the execution time and used memory space
if only WITHPYTHON is defined you will access only to UML and Python data, this means for instance that the operations cppDecl javaDecl mysqlDecl and idlDecl will not be defined for UmlBaseClassItem, this limits the amount of data managed by a plug-out and reduce the execution time and used memory space
if only WITHIDL is defined you will access only to UML and IDL data, this means for instance that the operations cppDecl javaDecl mysqlDecl and phpDecl will not be defined for UmlBaseClassItem, this limits the amount of data managed by a plug-out and reduce the execution time and used memory space
if only WITHMYSQL is defined you will access only to UML and MySQL data, this means for instance that the operations cppDecl javaDecl IdlDecl PythonDecl and phpDecl will not be defined for UmlBaseClassItem, this limits the amount of data managed by a plug-out and reduce the execution time and used memory space
the other combinations where only two of these three pre-processor variables are defined are illegal.
See upgrade plug-out.
It is possible to apply a plug-out on the project when Bouml is started through your shell or command line : bouml <project file> -exec <plug out> <plug out options> -exit
To not see the graphical interface replace -exec by -execnogui. Warning, under Windows the export of the diagrams doesn't work correctly with the option -execnogui.
<project file> indicates the model to load as usual.
<plug out> indicates the plug-out to apply on the project. The C++ generator is named cpp_generator, the Java generator java_generator, the Php generator php_generator, the Idl generator idl_generator, the HTML generator ghtml, the XMI generator gxmi and gxmi2. If necessary the full path of the plug-out have to be done, warning : under Windows this path must not contain space.
<plug out options> are the optional options you give to the plug out
-exit is optional and allows to exit from Bouml when the plug-out execution is done.
For instance (HTML generator options are given here, XMI generator options are given here) :
to start the xmi generator under Windows : "C:\Program Files\Bouml\bouml" "D:\...\aze\aze.prj" -exec C:\Progra~1\Bouml\gxmi -uml c:\aze.xmi windows-1252 -exit
to start the Html generator under Linux : bouml .../qsd/qsd.prj -exec /usr/lib/bouml/ghtml -flat -latin1 /tmp/qsd_html -del_html -del_css -exit
The exchanges between BOUML and the plug-outs are supported by a TCP/IP socket. When you ask BOUML to start a plug-out, it search for a free port number starting at 1024. In case you have a firewall it may be necessary to configure it.
To reduce the number of exchanges with BOUML and run faster, a plug-out does not ask for BOUML each time you want to get a value. The system classes read and memorize all the data of a given item the first time you access to one of them (with the restrictions allowed by WITHCPP, WITHJAVA, WITHPHP, WITHPYTHON, WITHMYSQL and WITHIDL). This is transparent for you until two plug-outs access to the same data, when one plug-out modify a value already read by the other, the second plug-out does not see the new value until it unload (an operation defined on UmlBaseItem) the object, then ask for the value.
A user property is a couple key – value, the value may be empty.
By default the user properties are not used, nevertheless they exist! It is the only way to add information concerning any item (without modifying BOUML !), and obviously they are accessible in the plug-outs. The alone limitation is that the keys and the values must contain string, may be on several lines ... even the editor called by the dialogs is not a multi-lines editor !
The plug-out genpro use the properties of the artifact on which it is applied to save its data and give them is a future usage (supposing the project saved !).
To see/modify them, select the last tab named User present in the dialog of any kind of item.
To compile the java files, go in the directory where the files are and do javac *.java (don't compile file by file because some files associated to the API contain several classes).
The easy way under Windows, Linux and MacOS X is to use QtCreator, to know which version of Qt is used to compile Bouml execute it then ask for About Qt in the global menu Help.
Previous : Use case wizard
Next : Project control