Extending the data model
From JMoney
pasdomvic This topic explains how plug-ins can extend the data model.
The JMoney core plug-in includes some core data model objects. These objects are:
- Commodity and classes that extend it
- Account and classes that extend it
- Transaction
- Entry
Unless you are interested only in writing plug-ins to create views of the data, you will probably need to add properties to the existing accounting objects. You may even want to create new classes of objects. This section describes the mechanisms for making these extensions to the data model. JMoney allows plug-ins to extend the data model. There are three different ways that a plug-in can extend the data model. To best understand the mechanisms for extending the data model, we first consider how a programmer might extend a data model in the traditional way. That is, assume the programmer is able to modify the base code and is not constrained to contributing only through plug-ins. There are three ways a programmer may extend the model:
- Add one or more properties to an existing class. To make this change, the programmer would add getter and setter methods to the class.
- Derive a new class from an existing class. To make this change, the programmer would create a new class that extends the existing class and would add getter and setter methods to the new class.
- Create a new base class that is not derived from any other class in the data model.
If two different programmers add properties to an existing class then any instance of that class will contain both sets of new properties. It may be that one programmer creates an object of this class and sets some properties but sets none of the properties added by the other programmer. Those properties not set are still properties of the object, even though they will contain default values.
If a programmer derives a new class by extending an existing class then the new properties in the derived class will only exist in objects that were created as instances of the derived class (or of classes further derived from the derived class). Another programmer may derive another class from the same base class. However no object can ever have both sets of new properties. Objects of a derived type inherit all properties from the base object. If another programmer later adds properties to the base class then those properties also become properties of all derived classes.
The above description of classes, properties, and inheritance may seem basic, but these same rules apply when plug-ins extend the data model. Plug-ins cannot add properties to pre-existing classes like the programmers above could do. However, plug-ins can make the equivalent extensions to the data model, and the above rules still apply.
Before you can get your plug-in to add properties to the data model, you must first decide which of the three different methods for adding properties applies. Are you adding properties to an existing class of objects? For example, suppose you are writing a plug-in to keep track of the interest rate that you are being paid on each of your bank accounts. To do this, you will need to add an extra property to the bank account class.
For a second example, suppose you are writing a plug-in to keep track of a stock brokerage account. You will need a class of objects representing stock. These objects would have properties such as the name of issuing company and the type (security or bond). You could use the currency class to represent stocks and bonds. You could add the properties to the currency class. These properties would not be applicable if the object represented a currency, and the currency properties (such as the currency code) would not be applicable for stocks. However, this is not the best solution. Better would be to derive a new class from the base commodity class.
For a third example, suppose you are writing a plug-in to support recurring transactions. You would add a new class of object, not derived from any other object, to represent a recurring transaction.
Most of the steps required to add properties are the same, regardless of which of the above three methods are used. For a plug-in to add properties, the plug-in must create and register a 'property set'. If a plug-in adds properties to more that one class in the data model then the plug-in must define multiple property sets. For example, a plug-in to track stock brokerage accounts creates a class to represent stock that is derived from the base commodity class, it adds properties to the bank account class, and it adds a boolean value to the base commodity type to indicate if that commodity may be held in a stock brokerage account. The plug-in would have to create three property sets.
Regardless of which of the three ways is used, a set of properties is being added to the data model. A set of properties added by a single plug-in in a particular place in the data model metadata is known as a property set.
This section describes the steps you must take to add a property set. You can only add properties to the data model by adding property sets. If you want to add a single property to an existing class then you must create a property set that contains a single property.
For every property set added by a developer, the developer must provide the following two classes:
- An implementation class. The implementation class must contain getter and setter methods for every scalar (non-list) property. The implementation class must also provide other methods such as two forms of constructor. JMoney will look for these methods when the JMoney workbench is initialized. If an implementation cl
