Developing Plug-Ins - IModelFactory
This tutorial is brought to you by Jan Thielemann from evenos GmbH (www.evenos-consulting.de). If you have questions, criticism or improvement suggestions, feel free to visit me (Jan.thielemann) or write me an email
Goal of this tutorial
The goal of this tutorial is to show, how you use the IModelFactory service in you plug-in project. The reason why you want to use the model factory service is, that you can provide your own model for custom tables and iDempiere will make use of them (e. G. the beforeSave method gets called). Also if you want to use the Query class, it is necessary to provide your own models. Otherwise, a Query will return a "GenericPO" instead of your model class.
Before you start this tutorial, you should take a look at the follwing tutorials:
- Developing Plug-Ins without affecting the Trunk
- Developing Plug-Ins - Get your Plug-In started
- Developing Plug-Ins - ModelValidator
X_, I_, M? Which class is for what?
In iDempiere we have different classes for our models. The toplevel class is called PO which stands for Persistent Object. Every models inherits it's methods. If you generate models or take a look at the existing ones, you will see that most of the tables have a X_ and I_ class.
The I_ class is an interface which has information about the table and it's columns. It has a constant for the table name, it's ID in the Application Dictionary (which is loaded dynamically via MTable.getTable_ID()) and every column in the table. It also has the template for all the getter and setter methods.
The X_ class is the basic model of every table. Here PO is extended and the I_ class is implemented. The X_ class implements all the getters and is the first class which could apply custom business logic (but don't put your business logic in here, you will learn why in a second). If you take a look at the code, you can see that the getter and setters which are implemented here often do some kind of validation to the data and use the POs methods to persist the data.
The last class is the M class. Its naming scheme is "M" + "table prefix (if >=3 chars)" + "table name without spaces or underscores". So if my table is called eve_this_is_my_table, i would create it in the Application Dictionary as "EVE_This_Is_My_Table" (notice the camel case writing). My model would be called "MEVEThisIsMyTable". Feel free to not use the table prefix but i like it because it makes spotting custom models easier. So what is the use of this M class which is not implemented automatically by the model generator? Thats easy to explain. All your custom business logic goes into this class. Why not using the X_ class? Because your table can change over time and everytime, you can simply run the model generator to recreate your I_ and X_ classes but you would lose all your custom business logic if it were in the X class. So by creating a M class which extends the X_ class you can regenerate your models without losing any code or functionality.
What can you do in the M class? Some examples are:
- Overwrite the beforeSave(), afterSave(), beforeDelete(), afterDelete() model hooks
- Implement the DocAction interface to make your table act like a document
- Create special getters and setters (like MOrder.getLines())
After creating the plug-in and setting its dependencies, click on File>New>Other... and select "Component Definition" from the Plug-in Development section.
Click on next. Select your plug-in project and chose a file name and a general name. We often use "defaultmodelfactory.xml" and "my.domain.model.factory" for the filename/name but every other name is okay too. You don't need to set the class name yet because we haven't implemented one. Click on finish.
The next things we will need is:
- A Model
- A ModelFactory (which is just a class which implements IModelFactory
Notice that your model factory and your model class must be implemented in different classes. It will not work if you try to implement IModelFactory in one of your models. The good news is, you only need one model factory for all your custom models. For our tutorial, we will use a custom subclass of MOrder. Create the class MOrder_New which inherits from MOrder and implement the default constructors:
The second class only implements IModelFactory and is called MyModelFactory. In getClass() we check if the table name is equal to our custom models table name and return the model class if it is. In the both getPO() methods, we use our custom models constructors to create new instances.
Open the mymodelfactory.xml and click on the Browse button to select the MyModelFactory class. Also add a integer property called "service.ranking" with a positive value (>0).
On the Services tab, add the IModelFactory to the "Provided Services" section.
Basically thats all you need to do. To see that we realy did someting, open your custom model class again and add a console log in beforeSave()
Make sure that your plug-in is active in the run configurations
Start the client and make sure your plug-in is active
Now log in as GardenAdmin/GardenWorld and create a new Sales Order fill in all mandatory fields and click on save. Take a look at your console log, you should see the log from your custom model class:
Generating Models for custom Tables
If you don't just want to overwrite a core model but provide your own model classes you need to do some steps.
- Create your table in the database
- Create an entry for your table in the Table and Column window
- Open Eclipse and start the generate.model App
- As the Source Folder, choose the "src" folder of your Plug-in
- As the Package Name chose a package name of your choice or use org.compiere.model if you like
- As the Table Name chose your prefix (custom tables should have 3 letter prefix in the db) and add some characters to identify your table. For example, if your table is called eve_this_is_a_table, then you could enter "eve_this%". Make sure you use the correct upper/lower case writing!
- As the entity type, chose the entity type you selected in the DB. Normaly it's "U" for user maintained
- Check both checkboxed and generate your I_ and X_ class
- Feel free to implement a custom M class
- Make sure that in your modelfactory.xml you have a unique name (my.domainname.pluginname.model.factory is a good idea) and that you selected the right class
- Make sure there is no other model factory with a higher service.ranking property
- Make sure you have a seperate model/model factory class
- Make sure your plug-in is activated before you log in
- Make sure your MANIFEST.MF contains a row with "Service-Component: " and the path to your modelfactory.xml (e. g. "Service-Component: mymodelfactory.xml")