See: Description
Package | Description |
---|---|
org.tanjakostic.jcleancim |
jCleanCim is an open source tool for validation and documentation generation from Enterprise
Architect CIM and IEC61850 UML models.
|
org.tanjakostic.jcleancim.builder | |
org.tanjakostic.jcleancim.builder.ea |
Classes responsible for building in-memory UML model from EA repository (.eap model file).
|
org.tanjakostic.jcleancim.builder.ea.db | |
org.tanjakostic.jcleancim.builder.ea.japi | |
org.tanjakostic.jcleancim.builder.ea.sqlxml | |
org.tanjakostic.jcleancim.common |
Classes commonly used by several packages.
|
org.tanjakostic.jcleancim.docgen | |
org.tanjakostic.jcleancim.docgen.collector |
This package defines interfaces and classes responsible for collecting documentation and figures
from the UML model, or freely initialised through the API without any UML model.
|
org.tanjakostic.jcleancim.docgen.collector.impl | |
org.tanjakostic.jcleancim.docgen.collector.impl.ag | |
org.tanjakostic.jcleancim.docgen.writer |
Classes and interfaces responsible for document generation out of the UML model.
|
org.tanjakostic.jcleancim.docgen.writer.word |
Classes specific to writing MS documents.
|
org.tanjakostic.jcleancim.docgen.writer.word.doc |
Classes specific to writing MS documents by means of automation API through Java-COM bridge (Jacob); this implementation is
extremely slow (it requires MS Word application and the COM API is just slow), but it supports
both .doc and .docx MS Word formats.
|
org.tanjakostic.jcleancim.docgen.writer.word.docx |
Classes specific to writing MS documents in OpenXML format; this implementation is fast (it does
not require MS Word application), but it supports only .docx MS Word format.
|
org.tanjakostic.jcleancim.docgen.writer.xml |
Classes specific to writing IEC 61850 name space definition files.
|
org.tanjakostic.jcleancim.experimental.builder.rdfs |
FIXME: This is experimental and absolutely not tested - don't use!
|
org.tanjakostic.jcleancim.experimental.builder.xsd |
The package contains the
ModelBuilderFromProfiles , which can
parse: the CIM profiles in "xsd" format, as
generated with CIMTool. |
org.tanjakostic.jcleancim.model |
Classes being created by a builder or with the API (code) to hold the in-memory UML model.
|
org.tanjakostic.jcleancim.statistics |
Classes responsible for tracking and reporting model statistics.
|
org.tanjakostic.jcleancim.util | |
org.tanjakostic.jcleancim.validation |
Classes responsible for validating the model and the rules to apply.
|
org.tanjakostic.jcleancim.xml |
jCleanCim is an open source tool for validation and documentation generation from Enterprise Architect CIM and IEC61850 UML models.
Note: The content below is hard to keep up to date. Please refer to the jCleanCim presentation, available in the documentation directory.
This is jCleanCim open source application, initially developed to perform validation of CIM EA model file, then extended to do clean-up of left-overs from Rose and to show some basic statistics (thus addressing combined CIM issue #1103). Finally, it has been extended to allow for IEC (and custom) document generation, mainly driven by special needs of generating IEC 61850-7-3 and IEC 61850-7-4 from UML model developed by ABB and handed over to IEC TC57 WG19 in October 2009. On the fly, the support for CIM-based IEC documents (IEC 61970-301 and IEC 61968-11) has been added - after all, this was an easy part :-).
Since February 2010, jCleanCim has been used by CIM editors of IEC TC57 WG13, WG14 and recently WG16 to generate IEC 61970-301, IEC 61968-11 and IEC 62325-301 documents, respectively, as well as for the documentation describing CIM extensions developed in the European FP7 project ADDRESS.
Since September 2010, it has also been used by 61850 UML taskforce of WG10 to validate IEC 61850 UML and to automatically generate IEC 61850-7-4 and IEC 61850-7-3. As other IEC working groups start moving their IEC 61850-based specifications to UML as master model, jCleanCim will allow for automatic document generation for these, as well. Furthermore, since 01v06, the tool supports serialisation of the UML model of IEC 61850 to an XML format, that would be suitable for publishing on the web, and in support of the WebAccess taskforce of WG10. As a by-product, the same feature is available for CIM UML model.
NOTE: From this point on, the documentation is likely obsolete; we try to maintain up to date the jCleanCim presentation, so have a look there.
jCleanCim has four main functions:
In addition to support for the standard IEC TC57 CIM and custom CIM extensions compliant with CIM desing rules, jCleanCim supports the same functionality for the UML model of IEC 61850 being developed by the 61850 UML taskforce. Having both families of standards in UML is expected to facilitate one day harmonisation efforts between CIM and 61850, lead by IEC TC57 WG19. Since the IEC 61850 UML model is still not a standard, in the following we refer to CIM only, although the descriptions apply to the UML model of IEC 61850 as well.
(TODO: needs update)
Intended users are primarily those who edit CIM UML and publish its documentation, thus:
If you are already a user of the excellent CIMTool, you may wonder where within the process of CIM development and maintenance the jCleanCim fits. The answer is:
See readme file.
See readme file.
See readme file.
Project's input directory contains a very small model file (you need at least one model file to run jCleanCim at all), and a sample template file (required for doc generation only).
base-small.eap is a tiny subset of IEC 61970 UML plus home-made dumb extensions, with intentionally-introduced several modelling bugs and constructs never supposed to be found in CIM - this is for testing purposes. You can use base-small-template.doc and tailor it for your needs to produce the MS Word documentation.
Tailoring the template for your needs means modifying, adding or removing different kinds
of Placeholder
s.
If you want to run jCleanCim with your own models (and potentially template files), you need to copy them to the input directory.
This directory also contains a blank image file that must be available when running jCleanCim for certain scenarios (e.g., if you don't generate documentation, but only run validation, this file will be used in place of real UML diagrams).
After you have unzipped the eclipse-independent binary distribution
(jCleanCim-[version]-bin.zip), you will be using the run script
run.bat
from console.
cmd
. This will open a
console window.
cd
followed by a space. From the file
explorer, just drag and drop the directory where you have unzipped the binary distribution
onto the console window (so you don't have to type the whole path), then press enter. This
will change the directory to where your jCleanCim has been installed.
run
and press enter. This will run the
jCleanCim jar with default configuration (validation and statistics) and the provided example
files.
After you have unzipped the eclipse-independent source distribution
(jCleanCim-[version]-src.zip) and installed Apache
ant, you will be using the Apache ant script
build.xml
from console.
cmd
. This will open a
console window.
cd
followed by a space. From the file
explorer, just drag and drop the directory where you have unzipped the source distribution
onto the console window (so you don't have to type the whole path), then press enter. This
will change the directory to where your jCleanCim has been installed.
ant jCleanCim
and press enter. This will build
the jCleanCim jar from sources and run it with the default configuration (validation and
statistics) and the provided example files. To see all available ant targets contained in the
ant build file, type ant -p
(or ant
-projecthelp
) and have a look at the graph of
targets and their dependencies.
Alternatively, you may want to unzip the directory and import the project into your eclipse installation. Note: If you already have an earlier version of jCleanCim in your eclipse workspace, you will first have to rename old jCleanCim project before importing new one. For example, if you want to import new version 01v04, rename first your existing jCleanCim project to jCleanCim-01v03, then import the new one. If you want to keep the old project jCleanCim-01v03 and use it, you will also have to update the build path for the directory where dll-s reside, otherwise eclipse shows you classpath error (eclipse does not use relative paths for dlls directories!).
After you have imported the eclipse existing project from unzipped source distribution (jCleanCim-[version]-src.zip), you should create the default eclipse launch configuration as follows:
src
directory
org.tanjakostic.jcleancim.JCleanCim
This will launch the application and also create the run configuration, that you can later on copy to create custom configurations. Cached launch configurations are available from the eclipse "Run" icon (green icon with white arrow).
Note that you can also open the ant build file from within eclipse (Window / Show Views / ant) and run any of its tasks from the eclipse Outline window, the same way as from the console.
To configure any run of jCleanCim application, you use the standard Java properties file
available in the project's config directory. Default name for that properties file is config.properties and you can override
this default with a command line argument if you want to use different stable configurations for
different jCleanCim runs - see documentation in the application class JCleanCim
and the configuration class Config
.
The supplied default properties file contains reasonable defaults, and several tested configurations are commented. By default (out of the box), jCleanCim will run validation and statistics on base-small.eap model file, and will not generate any documentation.
Project's config directory contains also the logging configuration file log4j.xml. We have set up the console output
level to INFO (within the element
appender name="CONSOLE"...
), and the level for everything else to the most verbose, TRACE (within the element
logger name="org.tanjakostic.jcleancim"
). The first time you run jCleanCim application, the project's log
directory gets created automatically.
If you get too noisy log files, you can dicrease the jCleanCim logger level in the log4j.xml file, from TRACE to DEBUG. If you want to post the jCleanCim log file with a model release, you can either:
To select what functions of jCleanCim to run, you need to set one or more of the main properties
in the config/config.properties file:
validation.on
,
statistics.on
and
docgen.on
. In every case, you have to provide a valid EA model file name to work with, in the property
model.filename
. That file is expected to be on the jCleanCim classpath, so the best is to put the file in the
input directory which is already set to be on the
classpath.
Typical usage will be to first enable validation and statistics mode after you have edited the model, then address the problems in the model, and revalidate before releasing. Here is an example of a minimum config.properties file to do that:
model.filename = base-small.eap validation.on = true statistics.on = true validation.scope =
If you are validating IEC 61850 UML models, there are several other properties; see
documentation in Config
.
If you have a big model, with potentially parts that are informative/buggy, you may want to set
a filter and perform initial validation of your changes for only some top-level packages. For
instance, to validate only standard CIM packages IEC61970 and IEC61968, you would set the
validation.scope
property so:
validation.scope = WG13, WG14
and to validate only custom (non-IEC) extensions:
validation.scope = OTHER_CIM, OTHER_IEC61850
It is recommended to validate the full content of the EA model (by leaving the value of validation.scope
property empty) at least before releasing the model
, to ensure there are no cross-package issues. See classes in the package org.tanjakostic.jcleancim.validation
for available validators and rules they fire - the names of
classes should be descriptive enough.
If you want to generate IEC (or custom) MS Word documentation from the UML model, in addition to
the model file name in config/config.properties
you must provide the names for template (input) file, the resulting (output) file, and enable
document generation by setting the property
docgen.on = true
.
The template file is a regular MS Word document (not Word template with .dot
extension), in which you put placeholders to control what jCleanCim should pick from the UML
model and print into MS Word document. Detailed description of available placeholders and their
usage is provided in the Placeholder
class, and the
templates distributed with jCleanCim in the project's input
directory should serve you as examples (of what is correct and what is not). If using your own
template, you should put it into that directory before running jCleanCim for document
generation.
When generating documentation, jCleanCim does the following:
output
directory, created
automatically the first time you run the document generation,
You can safely run document generation several times with the same name of the output file,
without overwriting existing output files - if the output file exists, jCleanCim will rename it
by appending a system nanosecond time. The disadvantage is that you will need to delete those
discarded files from the
output
directory from time to time, but at least nothing gets lost without your control.
You may want to disable validation and statistics when enabling document generation to have the console log focused on document generation only.
Because document generation takes pretty long, you will first want to ensure that the placeholders in your template are correct, without generating the full package content. Here the minimum configuration to do this for a CIM model (IEC61850 model needs more properties; see config/config.properties file):
model.filename = base-small.eap docgen.on = true profiles.docgen.on = docgen.inTemplate = base-small-template.doc docgen.outDocument = base-small.doc docgen.analysePlaceholders = true
Running only placeholder analysis (
docgen.analysePlaceholders=true
) will still produce the output document, but without UML package contents (classes, attributes,
etc.). More importantly, that half-baked output document will contain placeholder errors, if any
- do text search for string "$ERROR".
After you have fixed the placeholders in the template, you can reset
docgen.analysePlaceholders
to empty string to generate the full documentation.
There are further options documented in Config
and in
properties file config/config.properties.
Playing with the provided sample small model and template files will hopefully get you started.
When generating official IEC documentation, the template should contain the IEC styles
(this is probably already the case with CDV or FDIS documents that you as editor already have).
To prevent MS Word exceptions when generating non-IEC documentation for extensions, jCleanCim
defines default MS Word styles as replacement for the IEC styles. So, for example, 'Caption' is
used if 'FIGURE-title' and 'TABLE-title' are not present in the template, or 'Normal' is used if
'PARAGRAPH' is not present. Below is the code snippet of the static initialiser for Style
for the full list of default mappings: first
argument is IEC style name and the second is the MS Word default style:
para("PARAGRAPH", "Normal"), fig("Picture", "Normal"), figcapt("FIGURE-title", "Caption"), tabcapt("TABLE-title", "Caption"), tabhead("TABLE-col-heading", "Normal"), tabcell("TABLE-cell", "Normal"), h1("Heading 1", "Heading 1"), h2("Heading 2", "Heading 2"), h3("Heading 3", "Heading 3"), h4("Heading 4", "Heading 4"), h5("Heading 5", "Heading 5"), h6("Heading 6", "Heading 6"), h7("Heading 7", "Heading 7"), h8("Heading 8", "Heading 8"), h9("Heading 9", "Heading 9");
It is essential to use correct styles for paragraphs containing figure and table captions in the template, because jCleanCim must deduce the number of figures and tables already existing in the template to calculate on the fly the correct numbering for new figures and tables (when inserting/appending the documentation for the UML model elements and diagrams). If jCleanCim throws an exception during document generation, it is very likely that the MS Word threw exception due to wrong/inexisting/negative number for the figure or table caption. Note: We cannot check those numbers from within the code, because the MS Word automation API does not provide reliable access to them. In the worst case, when we catch an exception from MS Word, we gracefully close the MS Word document and exit the MS Word application, before exiting jCleanCim.
Document generation may take pretty long, depending on how many classes the UML model has. The reason is that MS Word updates its fields evey time there is a table or any numbered paragraph (heading or figure/table caption) added to the document. To make that time somewhat shorter, consider the following when editing the template:
Since version 01v03, jCleanCim has the MS Word application run in background by default (which is faster than having the window visible and updating all the time).
Doc generation obviously relies on MS Word automation API, accessed from within Java through Java-COM bridge (Jacob). With certain MS Word files (used as jCleanCim template), we encounter from time to time issues when invoking COM objects for unknown reason, and with undetermined patterns (= an absolute horror for a programmer!). Therefore, the Java implementation of the writer catches those COM exceptions, prints the stack trace and attempts to continue, so you get at least some of the desired output.
Here some known issues related to MS Word automation API:
UndoClear
) in attempt to clear cache
of the running Word instance, but this call sometimes fails for an unknown reason. Disabling
change tracking, and spell checking in styles 'PARAGRAPH', 'TABLE-cell' and 'Normal' in the
template document may help here.
If the problems persist, feel free to help fixing jCleanCim/Jacob/MS Word stuff.
If despite that we cannot find a workaround, we should convince IEC to allow us to generate our documents at least as HTML (or still better, as XML), to get rid of binary dependencies on MS Word.
All that said, we have sucessfully generated:
We have also demonstrated the generation of Ed.2 IEC 61850-7-4 and IEC 61850-7-3, but these auto-generated documents from UML are not the official IEC documents yet.
The requirements for generation of the above documents (and what will be needed for IEC 61850-7-2 and other IEC CIM and 61850 family of standards) are the highest priority ones at this moment.
Once after you've fixed bugs or added new features to jCleanCim, follow these steps to build and publish the three jCleanCim distributions:
project.version
.
ant clean, unzip-all
and verify that the content unzipped under the
build directory is ok.
jCleanCim-[version]
Copyright 2009-2015 Tatjana (Tanja) Kostic