OJBDoc is an application that will read an OJB repository xml file, analyze it and then inserts documentation into an instance of the Confluence wiki.
Requirements
This application has only been tested on Linux.
Installation
- Install Python, the dependent libraries and dependent applications.
- unzip and install the OJBDoc application into a target directory
- edit the OJBDoc.conf file to reflect the desired Confluence username, password and space.
Usage
OJBDoc is a command line utility.
lohnk@glacier:~/project/ojbdoc/000/ojbdoc> ./OJBDoc.py --help
This routine runs through an OJB-repository file producing and inserting
pages documenting the database into an instance of Confluence
-C, --clearAllComments
clear out all persistent comments
-c, --config
specify the location and name of the config file (default: ./OJBDoc.conf)
-b, --confluencePassword
the password of the Confluence User (default: )
-A, --confluenceSpace
the name of the space to be used in Confluence (default: )
-a, --confluenceUserName
the name of the Confluence User (default: )
-x, --confluenceXMLRPCPath
the URL for Confluence's XML-RPC service (default: http: -d, --diagramsURL
the base url for the images (default: )
-?, --help
print this list
-i, --indexPageName
the name of the index page to be used as the root page (default: Database Model)
-m, --moduleList
a quoted space delimited list of modules to include. An empty list selects all modules. (default: )
-n, --noDeploy
if present, this flag prevents updating of Confluence (used in debugging)
-r, --repository
location and name of the repository file (default: ./OJB-repository.xml)
-R, --rsyncDiagrams
a location to put the images in the form useful to rsync \[user@]host:destination
-s, --sourceCodePath
the base path of the source code (default: ./)
-t, --templateFilePath
the path to the template and abbreviation dictionary files (default: ./)
-v, --verbose
print what's going on
Any of the long option names can be included in the configuration file or provided as environment variables. Options listed on the command line override the configuration file. The configuration file overrides options that came from the environment.
--clearAllComments
This application produces documentation in Confluence that can be annotated. A Confluence user can edit the generated pages by adding text to any table cell with "Comment" as the header. In addition, the space between any outline numbered header and a table or inset below it is also editable. These comment areas are preserved between runs of OJBDoc. This option overrides that preservation and clears the comments.
--config
This specifies the location and name of the config file. It defaults to ./OJBDoc.conf
--confluencePassword
The password to allow OJBDoc to log in to Confluence. While this option can provided in the configuration file, some may prefer to require it provided at run time via the command line.
--confluenceSpace
The name of the space in Confluence that should receive the inserted pages.
--confluenceUserName
The log in name to use when connecting to Confluence.
--confluenceXMLRPCPath
This is a URI for Confluence's xmlrpc interface. Generally, this is in the form of http://localhost/rpc/xmlrpc
--diagramsURL
OJBDoc generates simple ER diagrams for each table and its immediate relations. Because Confluence 1.3.x does not have an xmlrpc interface for attaching documents to pages, these images will have to live elsewhere. This option gives the base URL fragment used to specify the location of the images.
--indexPageName
This is the name of the page within Confluence that is to serve as the index
--moduleList
This is a quoted, space delimited list of path fragments from class names. As OJBDoc moves through the OJB-repository.xml file, it only considers classes that contain path fragments from this list. If the list is empty, it will document all classes that it encounters.
--noDeploy
Primarily used in debugging, this option prevents OJBDoc from actually logging into Confluence.
--repository
The location and name of the OJB repository file. This must be a valid xml file and not an xml file fragment.
--rsyncDiagrams
The location to put the diagrams since they cannot be automatically attached. The string should be of the form [user@]host:destination which will be passed directly to rsync as the destination. Because rsync generally requires authentication and there is no opportunity to provide such, a mechanism such as sshagent should be used to provide authentication. If no value is given to this option or this option is not present, the application will not copy the diagrams.
--sourceCodePath
This is the path for a local copy of the source code so that OJBDoc can quote references.
--templateFilePath
Internally, OJBDoc uses Cheetah templates to create the text of each inserted Confluence page. This option gives the path to the template files.
--verbose
This program can take considerable time to run. This option makes the application periodically output what its doing to assure the user that it isn't just spinning its wheels.
Limitations
This application was written for a specific project and then enhanced for use in the Kuali project. As such, it is pretty specifically taylored for the situtations it was likely to encounter in those projects.
- This program handles only simple table relationships. It has not been designed for or tested on some of the more exotic table/class relationships that OJB is capable of supporting. This includes aggregation and subclassing.
- Confluence does not have an xmlrpc interface for attaching files to pages. Therefore the images produced by this program will have to manually loaded into Confluence or hosted on an external web server.
Internals
the repository internal representation
