Object Model Storage

Javelin stores your object models/design, but not your source code, in text files which are revision control system friendly (eg., CVS, Subversion etc.,). These files have a .vcm extension which stands for Visual Classworks Model (Visual Classworks is the C++ sister product of Javelin). They use a very compact text format and therefore load and save extremely quickly so switching between class diagrams is virtually instant. Your source code is stored in the normal way - in .java files as always. Javelin does not store any source code in it's .vcm files.

Location of the .vcm files

Javelin expects to open .vcm files in the root of the source tree of any project. This is the directory in which all of the package directories are contained. Whenever Javelin accesses a source file to update it to reflect design changes it uses relative addressing based on the package name to locate the source file. The addressing is relative to the root of the source tree where the .vcm lives. This is why it is important that .vcm files are situated in the root of the source tree (typically called 'src').

c:/dev/myproject
                /build/
                /lib
                /src   <---- your .vcm files live in here
                    /com/acme/petshop/model
                                           /Cat.java
                                           /Dog.java

Whenever you create a new project in Javelin be sure to specify the root of your source tree as the directory to store it in.

Code Managed/Non Code Managed Classes

In a Javelin class diagram every class is either code managed or non code managed. Javelin will initially generate and then manage the source code of managed classes but will not touch the source code of non managed classes. Javelin will modify the class definition, method signatures and attributes in a managed source file to reflect changes made to the class via the class diagram. All source code in method bodies in the source file will be preserved. All code in sections marked with the comment keyword //-[keep...] will be preserved. Javelin generates the class source code for a managed class when you first create it and creates various section markers to enable it to keep the source code synchronized with the model. Do not make changes to any of these markers.

NOTE: it is important that a class is only ever managed by a single class icon. The same class can be represented by class icons in multiple class diagrams but only one of these class icons should be responsible for managing the source code to avoid conflicts. The other icons representing that class should have the "Do not manage" check box selected in the Class' properties.

Multiple .vcm files

Typically a project will have many .vcm files, each one holding a single class diagram. It is good practice to break a large project up into many different .vcm/class diagrams to avoid clutter.

Saving .vcm files

You can explicitly save a .vcm file whenever you want but Javelin automatically saves .vcm files whenever it closes one or whenever it opens another one. So it is very rare that you will ever need to explicitly need to save in Javelin. Given that Javelin keeps your design and code synchronized it doesn't make sense to not save a .vcm when closing it.

A single class diagram per .vcm file

There are a number of approaches that design tools can take to the manner in which design information is stored. They can store all design information, class diagrams and all class details and relationships in a single monolithic repository - which is actually easier for the tool writer to implement - or it can work with a low granularity approach where each class diagram is stored in a separate file. The problem with the monolithic repository is teamwork and revision control: typically more than one person works on a given project. With a monolithic repository file, merging changes made by multiple developers into a revision control system becomes extremely burdensome with a high chance of conflict and error. With the lower granularity, class diagram per .vcm file approach that Javelin takes collaborative development is a lot more pleasant and less error prone.

Importing related files

There are many cases where Javelin automatically generates required import statements. It does this for associations (one-to-one, one-to-many etc.,), extends (inheritance) and implements relationships - so by merely establishing these relationships between your classes in Javelin the required imports will be set up in the source files automatically. Often less explicit relationships exist: these are typically when a method takes a class as a parameter or uses a class in its method body that isn't covered by the more explicit types of relationships. We call these "depends" relationships. You can establish a "depends" relationship and the dependent class' source code will be set up to contain an import statement importing the other class. Depends relationships are quite frequently used to import functionality from third party APIs/libraries or those classes in the java.* package.

It is possible to directly add your own import statements by right clicking on a class and choosing "Edit keep section > Before class declaration..." and adding them in the inbuilt editor.

Whether you add imports via directly typing them or by "depends" relationships is up to personal preference. Using "depends" relationships makes refactoring easier because if a "dependee" class' name or package is changed the source code of all dependent classes is automatically updated to reflect the change. Explicitly typed import statements, on the other hand, would have to be adjusted manually.

Importing shortcuts

There are many situations in which a set of specialized clases extend an abstract super class. The abstract superclass often has methods that are overridden in the base classes and reference classes in their parameter list that are not in the current package and so require importing. Normally each sub class has to explicitly import the same set of classes as the superclass. This gets monotonous so Javelin implements a short cut in regard to abstract classes - all immediate subclasses of an abstract superclass automatically import the same set of "depends" classes as the superclass.

Quite often it's convenient to mark a superclass as Abstract even though it has no abstract methods, just so that this shortcut kicks in and it's depends are automatically imported by the subclasses.

NOTE: this is one of the few aspects of Javelin in which an explicit "Force synchronization of all classes" is required because when adding or modifying a relationship to a class only the classes directly involved in the relationship are resynchronized. Being subclasses they are not directly involved in any changes to their superclass' depends relationships and so are not automatically resynchronized in this case. A simple click on the appropriate tool bar button causes the appropriate imports to be generated in the subclasses.

Per class diagram "default" package

Each class diagram's .vcm can have a different default package configured for it via Options | Project... from the main menu. In terms of Javelin's operation the 'default' package for a diagram is the default package any new classes created in that diagram will have by default. Of course you can change the package in the classes Properties form if you intended the class to be located in a different package.

Plain Old Java Object (POJO) development

Javelin supports and encourages development of software via POJOs. POJOs are plain old simple java objects that aren't littered with artifacts necessary for persistence, binding to databases etc., By using a transparent persistence technology such as JDO (a popular open source implementation is JPOX) and an 'almost transparent persistence' solution such as Hibernate you can achieve huge productivity gains. A popular architecture for POJO development is the "Exposed Model" architecture covered in Chris Richardson's book, "POJOs in Action" (excellent book - go out and buy it now!). It's a very easy to use, high productivity, high performance architecture which has a 'natural' object modeling feel. Try it - you'll never go back to EJBs, DAO or other high workload solutions.

The exposed model architecture encapsulates persistence technology specific code within 'service' and 'repository' classes. Basically services are where object model changes, additions and deletions take place and repositories are used to 'find' things - ie., they encapsulate the queries in a persistence technology independent way.

For services you usually need to wrap each service call in a try/catch construct with a transaction.begin()/commit()/rollback envelope. And for  optimistic transactions you typically want a retry mechanism. This gets tedious so in Javelin you can create a proxy service class that makes calls to the actual service methods that are wrapped within a transaction retry envelope by building a hierachy like that shown below:

You need to tell Javelin which class is the transaction management proxy service class by right clicking on the class and choosing "Pattern Wizard -> Transaction Managing Proxy". It requires an association, named 'impl', to be set up to the Service implementation class. The superclass Service class contains abstract methods that are implemented by both the ServiceImpl and TxnManagingProxy class. However, in the case of the TxnManagingProxy all abstract methods in the super class are implemented automatically whenever you regenerate the proxy class.

Just make sure all access to the service is via the proxy and then all service calls are automatically wrapped within a retyring (max 5 retries) transaction envelope. To add a new service method just add it to the ServiceImpl class then copy it and paste it into the Service superclass, change it to be abstract and then click on the proxy class and click on the regenerate button to tell it to generate the proxy method implementation of that new service method.