iDempiere en - User contributions [en]

NF9 Annotated Process Parameters

2022-03-14T02:20:23Z

Sjg: Created page with "= '''Feature:''' Annotated Process Parameters = '''Goal:''' Development '''Developer:''' Saulo Gil '''Feature Ticket:''' [https://idempiere.atlassian.net/brows..."

= '''Feature:''' Annotated Process Parameters =

'''Goal:''' Development

'''Developer:''' [[User:Sjg|Saulo Gil]]

'''Feature Ticket:''' [https://idempiere.atlassian.net/browse/IDEMPIERE-5025 IDEMPIERE-5025]

'''Description:'''

This feature was created in order to simplify the task of reading process parameters by using the new @Parameter annotation. Here's a comparison between new and the traditional way of achieving this goal, using the OrderBatchProcess class as reference.

''Using this feature''

@org.adempiere.base.annotation.Process
public class OrderBatchProcess extends SvrProcess
{
@Parameter
private int p_C_DocTypeTarget_ID = 0;
@Parameter
private String p_DocStatus = null;
@Parameter
private int p_C_BPartner_ID = 0;
@Parameter
private String p_IsSelfService = null;
@Parameter
private Timestamp p_DateOrdered_From = null;
@Parameter
private Timestamp p_DateOrdered_To = null;
@Parameter
private String p_DocAction = null;
@Parameter
private String p_IsDelivered = null;
@Parameter
private String p_IsInvoiced = null;

protected void prepare (){ /* nothing else to do here */ }
}

''Traditional way''

protected void prepare ()
{
ProcessInfoParameter[] para = getParameter();
for (int i = 0; i < para.length; i++)
{
String name = para[i].getParameterName();
if (para[i].getParameter() == null && para[i].getParameter_To() == null)
;
else if (name.equals("C_DocTypeTarget_ID"))
p_C_DocTypeTarget_ID = para[i].getParameterAsInt();
else if (name.equals("DocStatus"))
p_DocStatus = (String)para[i].getParameter();
else if (name.equals("IsSelfService"))
p_IsSelfService = (String)para[i].getParameter();
else if (name.equals("C_BPartner_ID"))
p_C_BPartner_ID = para[i].getParameterAsInt();
else if (name.equals("DateOrdered"))
{
p_DateOrdered_From = (Timestamp)para[i].getParameter();
p_DateOrdered_To = (Timestamp)para[i].getParameter_To();
}
else if (name.equals("DocAction"))
p_DocAction = (String)para[i].getParameter();
else if (name.equals("IsDelivered")) {
p_IsDelivered = (String)para[i].getParameter();
} else if (name.equals("IsInvoiced")) {
p_IsInvoiced = (String)para[i].getParameter();
}
else
log.log(Level.SEVERE, "Unknown Parameter: " + name);
}
} // prepare

In case the class attribute name doesn't match the parameter name, we can use the name annotation attribute as follows:

@Parameter(name = "declaredName")
private String parameter = null;

[[Category:New Features|D]]
[[Category:New Features|A]]
[[Category:New Features v9|D]]
[[Category:New Features v9|A]]
[[Category:New Features Development]]

NF9 Virtual Column Lazy Loading

2022-03-14T01:56:03Z

Sjg: Created page with "= '''Feature:''' Virtual Column Lazy Loading = '''Goal:''' Development '''Developer:''' Saulo Gil '''Feature Ticket:''' [https://idempiere.atlassian.net/browse..."

= '''Feature:''' Virtual Column Lazy Loading =

'''Goal:''' Development

'''Developer:''' [[User:Sjg|Saulo Gil]]

'''Feature Ticket:''' [https://idempiere.atlassian.net/browse/IDEMPIERE-5126 IDEMPIERE-5126]

'''Description:'''

Virtual columns were loaded among the rest of the regular columns when instantiating a model class. This behavior was changed as a performance improvement, now virtual columns are queried on-demand whenever their ''getter'' methods are called. In case the developer wants to load virtual column along with regular ones, that can be achieved as shown below.

'''New constructor'''

testPo = new MTest(Env.getCtx(), testPo.get_ID(), getTrxName(), MTest.COLUMNNAME_TestVirtualQty);

One or many virtual columns can passed on as parameters after the trxName parameter.

testPo = new MTest(Env.getCtx(), testPo.get_ID(), getTrxName(), MTest.COLUMNNAME_TestVirtualQty, MTest.COLUMNNAME_AnotherVirtualColumn);

'''Using Query'''

new Query(Env.getCtx(), MTest.Table_Name, MTest.COLUMNNAME_Test_ID + "=?", getTrxName())
.setVirtualColumns(I_Test.COLUMNNAME_TestVirtualQty).first();

[[Category:New Features|D]]
[[Category:New Features|A]]
[[Category:New Features v9|D]]
[[Category:New Features v9|A]]
[[Category:New Features Development]]

Developing iDempiere: Create a new custom class model with window and tabs

2021-11-29T02:19:49Z

Sjg:

[[Category:Development|P]]
[[Category:Developer documentation‏‎]]
[[Category:Plug-In Development]]
__TOC__
=Introduction=
iDempiere can be extended by creating new class models for specific business requirements without editing code in the trunk so that your [https://en.wikipedia.org/wiki/Bespoke bespoke] development can be protected from system upgrades.

This tutorial will show you how to create a parent-child class model and a window with tabs and fields to create, update and delete data using the built-in functionality of iDempiere.

It is based on [https://www.youtube.com/watch?v=F1lFHS2riG4 this video] by Jan Thielemann from [http://www.evenos.de/ evenos GmbH].

The process is as follows:
* Create the underlying database tables to support the new class model;
* Create Table entries in the iDempiere dictionary to register the database tables;
* Create a Window and Tab for the parent table, with a Sub-Tab for the child table;
* Create a Menu entry to open the Window;
* Build a plug-in so that the new functionality can be deployed with the base application.

=Prerequisites=
The tutorial assumes that you have set up iDempiere in an Eclipse development environment. If you have not, follow these instructions for installing iDempiere for Development:
# [[Install Development Prerequisites]]
# [[Download the Code]]
# [[Setting up Eclipse]]
# [[Importing DB Seed Manually]]
# [[Running iDempiere within Eclipse]]

The tutorial also assumes that you know how to create PostgreSQL tables using a SQL editor such as the psql command line interface or a tool like [https://www.pgadmin.org/download/ pgAdmin3].

=New class model=
The first step is to create a new class model in the form of two database tables with a parent-child relation between them.

==Parent table==
Create the main parent table '''''eve_main''''' as follows:

<pre>
CREATE TABLE eve_main(
-- Mandatory columns
eve_main_id numeric(10,0) PRIMARY KEY,
eve_main_uu character varying(36) DEFAULT NULL::character varying UNIQUE,
ad_client_id numeric(10,0) NOT NULL,
ad_org_id numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,

-- User-defined columns
value character varying(40) NOT NULL,
name character varying(255) NOT NULL,
description character varying(255) NOT NULL,
help character varying(2000),
m_product_id numeric(10,0),
UNIQUE (ad_client_id, value)
);
</pre>

The iDempiere table naming convention is to prefix the table name with three or more letters specific to your project, followed by an underscore and the table name in camelCase. In this example, the table name is prefixed with ''eve_'', for the name of the company that Jan works for, Evenos.

The table must start with a set of mandatory columns that are used by iDempiere to manage the records and record activity for audit purposes. In the table above they are:
*'''eve_main_id''': the primary key of the table, named by adding the suffix '''''_id''''' to the table name;
*'''eve_main_uu''': a unique identifier, named by adding the suffix '''''_uu''''' to the table name;
*'''ad_client_id''': the identifier of the client or tenant;
*'''ad_org_id''': the identifier of the organisational unit within the client;
*'''isactive''': records can be deactivated to allow for logical deletes;
*'''created''': the date this record was created;
*'''createdby''': the user that created the record;
*'''updated''': the date this record was updated;
*'''updatedby''': the user that updated the record.

The recommended user-defined columns include:
*'''value''': the search key or code;
*'''name''': the display name;
*'''description''': long description;
*'''help''': help or comments.

The parent table includes a field ''m_product_id'' which is in the standard iDempiere table ''M_Product'', and it has a constraint that ensures that the contents of the ''client'' and ''value'' columns are unique in combination.

Note that columns with the 'NOT NULL' constraint will become mandatory fields in the window.

==Child table==
Create the child table '''''eve_sub''''' as follows:

<pre>
CREATE TABLE eve_sub(
-- Mandatory columns
eve_sub_id numeric(10,0) PRIMARY KEY,
eve_sub_uu character varying(36) DEFAULT NULL::character varying UNIQUE,
ad_client_id numeric(10,0) NOT NULL,
ad_org_id numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,

-- User-defined columns
eve_main_id numeric(10,0) NOT NULL references eve_main(eve_main_id),
value character varying(40) NOT NULL,
name character varying(255) NOT NULL,
description character varying(255) NOT NULL,
help character varying(2000),
UNIQUE (ad_client_id, value)
);
</pre>

This is just like the parent table, except it has a foreign key relationship to the parent.

=Table and Columns=
==Login as SuperUser==
The window for the new class models is created by configuring iDempiere to use the new tables, using the SuperUser login and System client, so browse to http://localhost:8080/webui/ and login as SuperUser and check the Select Role box:

[[File:GS01_Login_Select_Role.png|512px]]

Make sure the Client is System and the Role is System Administrator:

[[File:GS01_Role.png|512px]]

==Create the Table and Columns==
After login, select the create Table and Column button on the right of the ''Table and Column'' entry in the Favourites window:

[[File:GS01_Table_and_Columns.png|560px]]

Create the Table by entering the parent database table in the DB Table Name field:

[[File:GS01_Create_Main.png|980px]]

'''Note:'''
* the prefix and the table name have been capitalized so that when we build the plug-in, the iDempiere Model Generator generates Java classes with names that conform to the standard naming convention;
* the ''Database Access Level'' is set to 'All' to ensure that the table can be used by all Clients, including System;
* the ''Entity Type'' is 'User maintained' to protect the table from system upgrades.

See the Table and Column documentation for the usage of the other table attributes: [[Template:Table and Column (Window ID-100 V1.0.0)#TAB:_Table]]

Save the Table record, then click on the Processes cog to create columns from the database table:

[[File:GS01_Create_Columns.png|612px]]

The process will ask you to confirm that you want to create the columns:

[[File:GS01_Create_Database_Columns.png|480px]]

When the process has completed it will list the columns that were created:

[[File:GS01_Create_Columns_Success.png|320px]]

Now you have the new Table and Columns to work with:

[[File:GS01_Table_and_Columns_Created.png|1024px]]

Scroll through the Columns listed in the grid below and change their properties as required by the application. As an example, click on the Edit button on the left of the record for ''M_Product_ID'' to open up the details of the column:

[[File:GS01_Column_Details.png|1024px]]

Note that ''M_Product_ID'' is already in the system dictionary because it is a column in the table ''M_Product'' so some of the column attributes are already populated.

See the Table and Column documentation for the usage of each of the other Column attributes: [[Template:Table and Column (Window ID-100 V1.0.0)#TAB:_Column]]. The video has [https://youtu.be/F1lFHS2riG4?t=7m34s a detailed discussion] of all the various Column attributes.

Now repeat the exercise to create a Table entry for the child database table '''''eve_sub''''' and generate the columns from the database:

[[File:GS01_Child_Table_and_Columns_Created.png|1024px]]

We must link the child table to its parent, using the column ''EVE_Main_ID'', so select it and open it, then check the ''Parent link column'' attribute and save the change to the column:

[[File:GS01_Link_Child_to_Parent.png|1024px]]

Note that we could have done the same to the parent table ''EVE_Main'' above to link it to the ''M_Product'' table too.

=Window and Tabs=
We have created the entries for the two tables, so now we can create the window and tab for the parent ''EVE_Main'' and a sub-tab for the child ''EVE_Sub''.

==Create Window==
Click on the button to create a new window (on the right of the ''Window, Tab & Field'' entry in Favourites) and enter the name.

Uncheck the attribute ''Sales Transaction'' because it is not relevant, and save the record:

[[File:GS01_Create_Window.png|1024px]]

==Create Tab==
Click on the ''Tab'' tab under the window you created above to open a new screen for the tab.

Enter the name ''Main Tab'', and select the Table name ''EVE_Main_Evenos Main'' from the dropdown.

Check the attribute ''Single Row Layout'' and then save the record:

[[File:GS01_Create_Tab.png|1024px]]

Scroll down to the large ''Create Fields'' button on the tab screen and select it to generate the fields from the database table. Select ''OK'' on the confirmation screen:

[[File:GS01_Create_Tab_Fields.png|480px]]

When the process has completed it will list the fields that were created, and after you dismiss the popup confirmation, you will see them at the bottom of the tab screen:

[[File:GS01_Create_Tab_Fields_Created.png|1024px]]

You can click on the ''Field Sequence'' tab to adjust the field ordering.

Click on the cog in the toolbar to open a graphical editor to edit the layout of the fields:

[[File:GS01_Tab_Editor_Process.png|520px]]

The Tab Editor will open in a new window where you can add and remove fields, drag them around (by grabbing the field title), resize them (by double-clicking with and without holding down CTRL), and so on:

[[File:GS01_Tab_Editor.png|1028px]]

Watch [http://www.youtube.com/watch?v=F1lFHS2riG4&t=1190s the video] for a demonstration of the Tab Editor.

==Sub-Tab==
Now we must create the sub-tab for the child table, so click on the ''New Record'' icon and enter the details for the sub-tab.

Note that the ''Tab Level'' must be set to '''1''' because it is a sub-tab (the default level is 0).

Scroll down and click on the ''Create Fields'' icon to generate the fields for the sub-tab:

[[File:GS01_Create_Sub_Tab.png|1024px]]

=Menu=
You must create a Menu entry to use the new window, so click on the button to create a new menu (on the right of the ''Menu'' entry in Favourites).

Enter the name, set the Action to ''Window'' and use the dropdown in Window to find the window that you created above, and save the record:

[[File:GS01_Create_Menu.png|1024px]]

'''Note:''' the new menu entry will appear in the list of menu items on the left but it will not be active because menu items are loaded when the user logs in for the first time.

Log out and log in again to see the new entry in the Menu tree:

[[File:GS01 Menu Created.png|720px]]

Click on the new menu entry to see the new window with its main tab and the sub-tab below:

[[File:GS01 New Window.png|1024px]]

Watch [http://www.youtube.com/watch?v=F1lFHS2riG4&t=1525s the video] and test the new window.

=Plug-in=
At this point the new model is only available in the development environment, and it is implemented using default mechanisms that contain no Business logic. We need to build a plug-in to hold the new model, together with any bespoke logic that may be required, so that it can be deployed with the base system.

You can watch the video [http://www.youtube.com/watch?v=F1lFHS2riG4&t=1680s from this point] before you follow the summary of the process below.

==Plug-in Project==
The first step is to create a Plug-in Project.

If you have not already done so, create a sub-directory in your workspace for bespoke plug-ins to keep the codebase clean (in this example, the sub-directory is called ''zerlina-plugins'').

'''File > New > Other > Plug-in Project > Next >'''

[[File:GS01 New Plug-in Project.png]]

'''Note:'''
* ''Use default location'' box is unchecked so that the plug-in project location can be used instead;
* ''Target Platform'' is the Equinox OSGi framework.

[[File:GS01 New Plug-in Project 1.png]]

'''Note:''' the author has selected JavaSE-1.6 to ensure that the plug-in is backwards compatible with older servers.

Answer ''Yes'' if Eclipse asks you if you want to use the Plug-in perspective.

==Package for the model==
Now navigate to the '''''src''''' folder of the new project and create a new package:

'''Right-click on ''src'' > New > Package'''

[[File:GS01 New Java Package.png]]

'''Note:''' the name of the package is ''org.evenos.model''

==Model generator==
Generate the models with the model generator:

'''Run > Run Configurations... > model.generator > Run'''

After a few seconds the Model Class Generator will open:

[[File:GS01 Model Generator.png]]

'''Note:'''
* use the '...' icon in ''Source Folder'' to browse to the '''''src''''' folder of the project in the plug-ins sub-directory;
* ''Package Name'' is 'org.evenos.model';
* ''Table Name'' is 'EVE_%' to generate models for both tables;
* ''Entity Type'' is 'U' for User Maintained.

Refresh the project to see the newly generated model classes.

=='M' Classes==
Create two 'M' classes to hold the business logic for each of the two tables:

'''Right-click ''org.evenos.model'' > New > Class > Name: MEVEMain > Finish'''

Add two constructors and a generated serial version ID:
<pre>
package org.evenos.model;

import java.sql.ResultSet;
import java.util.Properties;

public class MEVEMain extends X_EVE_Main{

/**
*
*/
private static final long serialVersionUID = -4652910060540398746L;

public MEVEMain(Properties ctx, ResultSet rs, String trxName) {
super(ctx, rs, trxName);
// TODO Auto-generated constructor stub
}

public MEVEMain(Properties ctx, int EVE_Main_ID, String trxName) {
super(ctx, EVE_Main_ID, trxName);
// TODO Auto-generated constructor stub
}
}
</pre>

Repeat for '''''MEVESub''''':

<pre>
package org.evenos.model;

import java.sql.ResultSet;
import java.util.Properties;

public class MEVESub extends X_EVE_Sub{

/**
*
*/
private static final long serialVersionUID = -2076611601274220946L;

public MEVESub(Properties ctx, int EVE_Sub_ID, String trxName) {
super(ctx, EVE_Sub_ID, trxName);
// TODO Auto-generated constructor stub
}

public MEVESub(Properties ctx, ResultSet rs, String trxName) {
super(ctx, rs, trxName);
// TODO Auto-generated constructor stub
}
}
</pre>

To get some idea of what business logic is possible in these classes, look at the 'M' classes in the package 'org.compiere.model' in the project 'org.adempiere.base' which is the core of iDempiere.

==Dependencies==
The operation of the new plug-in is dependent on two other plug-ins, so use the '''Add...''' button to add 'org.adempiere.base' and 'org.adempiere.plugin.utils' to the plug-in manifest:

[[File:GS01 Manifest Dependencies.png]]

==Model Factory==
The plug-in requires a custom model factory to create the new class model instead of relying on the default model factory.
Create a new package <code>org.evenos.factories</code> with a new class <code>MyModelFactory</code>. Below we'll show different approaches for creating this factory.

===iDempiere 9.0 onwards===

====Annotation Based Factory====

This type of model factory will automatically scan at runtime one or more packages searching for model classes with the <code>@Model</code> annotation. This annotation is added automatically by the Model Generator to all X classes.

<pre>
package org.evenos.factories;

import org.adempiere.base.AnnotationBasedModelFactory;

public class MyModelFactory extends AnnotationBasedModelFactory {

@Override
protected String[] getPackages() {
return new String[] {"org.evenos.model"};
}

}
</pre>

====Map Based Factory====

With this type of model factory one must declare for each table:

* Association between table name and its model class
* Model class instantiation for numeric identifier
* Model class instantiation via <code>ResultSet</code>

<pre>
package org.evenos.factories;

import org.idempiere.model.MappedModelFactory;

public class MyModelFactory extends MappedModelFactory {

public MyModelFactory() {
addMapping(MEVESub.Table_Name, () -> MEVESub.class
, (id, trxName) -> new MEVESub(Env.getCtx(), id, trxName)
, (rs, trxName) -> new MEVESub(Env.getCtx(), rs, trxName));
addMapping(MEVEMain.Table_Name, () -> MEVEMain.class
, (id, trxName) -> new MEVEMain(Env.getCtx(), id, trxName)
, (rs, trxName) -> new MEVEMain(Env.getCtx(), rs, trxName));
}

}
</pre>

===iDempiere 8.2 and earlier===

The following approach shows how to implement a model factory from scratch, without using the base classes available since iDempiere 9.0. Following code is also compatible with iDempiere 9.0.

<pre>
package org.evenos.factories;

import java.sql.ResultSet;

import org.adempiere.base.IModelFactory;
import org.compiere.model.PO;
import org.compiere.util.Env;
import org.evenos.model.MEVEMain;
import org.evenos.model.MEVESub;

public class MyModelFactory implements IModelFactory{

@Override
public Class<?> getClass(String tableName) {
if(tableName.equalsIgnoreCase(MEVESub.Table_Name))
return MEVESub.class;

if(tableName.equalsIgnoreCase(MEVEMain.Table_Name))
return MEVEMain.class;

return null;
}

@Override
public PO getPO(String tableName, int Record_ID, String trxName) {
if(tableName.equalsIgnoreCase(MEVESub.Table_Name))
return new MEVESub(Env.getCtx(), Record_ID, trxName);

if(tableName.equalsIgnoreCase(MEVEMain.Table_Name))
return new MEVEMain(Env.getCtx(), Record_ID, trxName);

return null;
}

@Override
public PO getPO(String tableName, ResultSet rs, String trxName) {
if(tableName.equalsIgnoreCase(MEVESub.Table_Name))
return new MEVESub(Env.getCtx(), rs, trxName);

if(tableName.equalsIgnoreCase(MEVEMain.Table_Name))
return new MEVEMain(Env.getCtx(), rs, trxName);

return null;
}
}
</pre>

==Component Definition==
The custom model factory must be made known to the OSGi framework so that it will be invoked in preference to the default model factory.

Create a new folder 'OSGI-INF' in the project and then create a Component Definition file:

'''Right-click ''OSGI-INF'' > New > Other... > Plug-in Development > Component Definition > Name: ModelFactory.xml > Finish'''

Enter the following:

[[File:GS01 OSGI-INF 0.png|920px]]

'''Note:'''
* ''Name'' is 'org.evenos.newwindow.model.factory'
* ''Class'' is 'org.evenos.factories.MyModelFactory' (use the Browse button to find it)
* Click on ''Add Property'' to create the 'service.ranking' property with type Integer and value 100 which will ensure that OSGi uses the custom model factory in preference to the default version

Now add IModelFactory to the list of Provided Services on the Services tab of the Component Definition:

'''Click 'Services' tab > Provided Services Add.. > IModelFactory''' and save the definition file.

Finally, update the Manifest so that the Component Definition loads every service defined in the OSGI-INF directory by changing the last line as follows:
<pre>
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Newwindow
Bundle-SymbolicName: org.evenos.newwindow
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Require-Bundle: org.adempiere.base;bundle-version="4.1.0",
org.adempiere.plugin.utils;bundle-version="4.1.0"
Service-Component: OSGI-INF/*
</pre>

'''Note:''' this last step is optional, but the presenter of the video recommends it as good practise.

The video includes a useful discussion on building business logic into the 'M' Classes [http://www.youtube.com/watch?v=F1lFHS2riG4&t=2433s at this point].

=Close-out=
The plug-in is now complete, so you can build the product and deploy it for use.

Developing iDempiere: Create a new custom class model with window and tabs

2021-11-29T02:11:46Z

Sjg:

[[Category:Development|P]]
[[Category:Developer documentation‏‎]]
[[Category:Plug-In Development]]
__TOC__
=Introduction=
iDempiere can be extended by creating new class models for specific business requirements without editing code in the trunk so that your [https://en.wikipedia.org/wiki/Bespoke bespoke] development can be protected from system upgrades.

This tutorial will show you how to create a parent-child class model and a window with tabs and fields to create, update and delete data using the built-in functionality of iDempiere.

It is based on [https://www.youtube.com/watch?v=F1lFHS2riG4 this video] by Jan Thielemann from [http://www.evenos.de/ evenos GmbH].

The process is as follows:
* Create the underlying database tables to support the new class model;
* Create Table entries in the iDempiere dictionary to register the database tables;
* Create a Window and Tab for the parent table, with a Sub-Tab for the child table;
* Create a Menu entry to open the Window;
* Build a plug-in so that the new functionality can be deployed with the base application.

=Prerequisites=
The tutorial assumes that you have set up iDempiere in an Eclipse development environment. If you have not, follow these instructions for installing iDempiere for Development:
# [[Install Development Prerequisites]]
# [[Download the Code]]
# [[Setting up Eclipse]]
# [[Importing DB Seed Manually]]
# [[Running iDempiere within Eclipse]]

The tutorial also assumes that you know how to create PostgreSQL tables using a SQL editor such as the psql command line interface or a tool like [https://www.pgadmin.org/download/ pgAdmin3].

=New class model=
The first step is to create a new class model in the form of two database tables with a parent-child relation between them.

==Parent table==
Create the main parent table '''''eve_main''''' as follows:

<pre>
CREATE TABLE eve_main(
-- Mandatory columns
eve_main_id numeric(10,0) PRIMARY KEY,
eve_main_uu character varying(36) DEFAULT NULL::character varying UNIQUE,
ad_client_id numeric(10,0) NOT NULL,
ad_org_id numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,

-- User-defined columns
value character varying(40) NOT NULL,
name character varying(255) NOT NULL,
description character varying(255) NOT NULL,
help character varying(2000),
m_product_id numeric(10,0),
UNIQUE (ad_client_id, value)
);
</pre>

The iDempiere table naming convention is to prefix the table name with three or more letters specific to your project, followed by an underscore and the table name in camelCase. In this example, the table name is prefixed with ''eve_'', for the name of the company that Jan works for, Evenos.

The table must start with a set of mandatory columns that are used by iDempiere to manage the records and record activity for audit purposes. In the table above they are:
*'''eve_main_id''': the primary key of the table, named by adding the suffix '''''_id''''' to the table name;
*'''eve_main_uu''': a unique identifier, named by adding the suffix '''''_uu''''' to the table name;
*'''ad_client_id''': the identifier of the client or tenant;
*'''ad_org_id''': the identifier of the organisational unit within the client;
*'''isactive''': records can be deactivated to allow for logical deletes;
*'''created''': the date this record was created;
*'''createdby''': the user that created the record;
*'''updated''': the date this record was updated;
*'''updatedby''': the user that updated the record.

The recommended user-defined columns include:
*'''value''': the search key or code;
*'''name''': the display name;
*'''description''': long description;
*'''help''': help or comments.

The parent table includes a field ''m_product_id'' which is in the standard iDempiere table ''M_Product'', and it has a constraint that ensures that the contents of the ''client'' and ''value'' columns are unique in combination.

Note that columns with the 'NOT NULL' constraint will become mandatory fields in the window.

==Child table==
Create the child table '''''eve_sub''''' as follows:

<pre>
CREATE TABLE eve_sub(
-- Mandatory columns
eve_sub_id numeric(10,0) PRIMARY KEY,
eve_sub_uu character varying(36) DEFAULT NULL::character varying UNIQUE,
ad_client_id numeric(10,0) NOT NULL,
ad_org_id numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,

-- User-defined columns
eve_main_id numeric(10,0) NOT NULL references eve_main(eve_main_id),
value character varying(40) NOT NULL,
name character varying(255) NOT NULL,
description character varying(255) NOT NULL,
help character varying(2000),
UNIQUE (ad_client_id, value)
);
</pre>

This is just like the parent table, except it has a foreign key relationship to the parent.

=Table and Columns=
==Login as SuperUser==
The window for the new class models is created by configuring iDempiere to use the new tables, using the SuperUser login and System client, so browse to http://localhost:8080/webui/ and login as SuperUser and check the Select Role box:

[[File:GS01_Login_Select_Role.png|512px]]

Make sure the Client is System and the Role is System Administrator:

[[File:GS01_Role.png|512px]]

==Create the Table and Columns==
After login, select the create Table and Column button on the right of the ''Table and Column'' entry in the Favourites window:

[[File:GS01_Table_and_Columns.png|560px]]

Create the Table by entering the parent database table in the DB Table Name field:

[[File:GS01_Create_Main.png|980px]]

'''Note:'''
* the prefix and the table name have been capitalized so that when we build the plug-in, the iDempiere Model Generator generates Java classes with names that conform to the standard naming convention;
* the ''Database Access Level'' is set to 'All' to ensure that the table can be used by all Clients, including System;
* the ''Entity Type'' is 'User maintained' to protect the table from system upgrades.

See the Table and Column documentation for the usage of the other table attributes: [[Template:Table and Column (Window ID-100 V1.0.0)#TAB:_Table]]

Save the Table record, then click on the Processes cog to create columns from the database table:

[[File:GS01_Create_Columns.png|612px]]

The process will ask you to confirm that you want to create the columns:

[[File:GS01_Create_Database_Columns.png|480px]]

When the process has completed it will list the columns that were created:

[[File:GS01_Create_Columns_Success.png|320px]]

Now you have the new Table and Columns to work with:

[[File:GS01_Table_and_Columns_Created.png|1024px]]

Scroll through the Columns listed in the grid below and change their properties as required by the application. As an example, click on the Edit button on the left of the record for ''M_Product_ID'' to open up the details of the column:

[[File:GS01_Column_Details.png|1024px]]

Note that ''M_Product_ID'' is already in the system dictionary because it is a column in the table ''M_Product'' so some of the column attributes are already populated.

See the Table and Column documentation for the usage of each of the other Column attributes: [[Template:Table and Column (Window ID-100 V1.0.0)#TAB:_Column]]. The video has [https://youtu.be/F1lFHS2riG4?t=7m34s a detailed discussion] of all the various Column attributes.

Now repeat the exercise to create a Table entry for the child database table '''''eve_sub''''' and generate the columns from the database:

[[File:GS01_Child_Table_and_Columns_Created.png|1024px]]

We must link the child table to its parent, using the column ''EVE_Main_ID'', so select it and open it, then check the ''Parent link column'' attribute and save the change to the column:

[[File:GS01_Link_Child_to_Parent.png|1024px]]

Note that we could have done the same to the parent table ''EVE_Main'' above to link it to the ''M_Product'' table too.

=Window and Tabs=
We have created the entries for the two tables, so now we can create the window and tab for the parent ''EVE_Main'' and a sub-tab for the child ''EVE_Sub''.

==Create Window==
Click on the button to create a new window (on the right of the ''Window, Tab & Field'' entry in Favourites) and enter the name.

Uncheck the attribute ''Sales Transaction'' because it is not relevant, and save the record:

[[File:GS01_Create_Window.png|1024px]]

==Create Tab==
Click on the ''Tab'' tab under the window you created above to open a new screen for the tab.

Enter the name ''Main Tab'', and select the Table name ''EVE_Main_Evenos Main'' from the dropdown.

Check the attribute ''Single Row Layout'' and then save the record:

[[File:GS01_Create_Tab.png|1024px]]

Scroll down to the large ''Create Fields'' button on the tab screen and select it to generate the fields from the database table. Select ''OK'' on the confirmation screen:

[[File:GS01_Create_Tab_Fields.png|480px]]

When the process has completed it will list the fields that were created, and after you dismiss the popup confirmation, you will see them at the bottom of the tab screen:

[[File:GS01_Create_Tab_Fields_Created.png|1024px]]

You can click on the ''Field Sequence'' tab to adjust the field ordering.

Click on the cog in the toolbar to open a graphical editor to edit the layout of the fields:

[[File:GS01_Tab_Editor_Process.png|520px]]

The Tab Editor will open in a new window where you can add and remove fields, drag them around (by grabbing the field title), resize them (by double-clicking with and without holding down CTRL), and so on:

[[File:GS01_Tab_Editor.png|1028px]]

Watch [http://www.youtube.com/watch?v=F1lFHS2riG4&t=1190s the video] for a demonstration of the Tab Editor.

==Sub-Tab==
Now we must create the sub-tab for the child table, so click on the ''New Record'' icon and enter the details for the sub-tab.

Note that the ''Tab Level'' must be set to '''1''' because it is a sub-tab (the default level is 0).

Scroll down and click on the ''Create Fields'' icon to generate the fields for the sub-tab:

[[File:GS01_Create_Sub_Tab.png|1024px]]

=Menu=
You must create a Menu entry to use the new window, so click on the button to create a new menu (on the right of the ''Menu'' entry in Favourites).

Enter the name, set the Action to ''Window'' and use the dropdown in Window to find the window that you created above, and save the record:

[[File:GS01_Create_Menu.png|1024px]]

'''Note:''' the new menu entry will appear in the list of menu items on the left but it will not be active because menu items are loaded when the user logs in for the first time.

Log out and log in again to see the new entry in the Menu tree:

[[File:GS01 Menu Created.png|720px]]

Click on the new menu entry to see the new window with its main tab and the sub-tab below:

[[File:GS01 New Window.png|1024px]]

Watch [http://www.youtube.com/watch?v=F1lFHS2riG4&t=1525s the video] and test the new window.

=Plug-in=
At this point the new model is only available in the development environment, and it is implemented using default mechanisms that contain no Business logic. We need to build a plug-in to hold the new model, together with any bespoke logic that may be required, so that it can be deployed with the base system.

You can watch the video [http://www.youtube.com/watch?v=F1lFHS2riG4&t=1680s from this point] before you follow the summary of the process below.

==Plug-in Project==
The first step is to create a Plug-in Project.

If you have not already done so, create a sub-directory in your workspace for bespoke plug-ins to keep the codebase clean (in this example, the sub-directory is called ''zerlina-plugins'').

'''File > New > Other > Plug-in Project > Next >'''

[[File:GS01 New Plug-in Project.png]]

'''Note:'''
* ''Use default location'' box is unchecked so that the plug-in project location can be used instead;
* ''Target Platform'' is the Equinox OSGi framework.

[[File:GS01 New Plug-in Project 1.png]]

'''Note:''' the author has selected JavaSE-1.6 to ensure that the plug-in is backwards compatible with older servers.

Answer ''Yes'' if Eclipse asks you if you want to use the Plug-in perspective.

==Package for the model==
Now navigate to the '''''src''''' folder of the new project and create a new package:

'''Right-click on ''src'' > New > Package'''

[[File:GS01 New Java Package.png]]

'''Note:''' the name of the package is ''org.evenos.model''

==Model generator==
Generate the models with the model generator:

'''Run > Run Configurations... > model.generator > Run'''

After a few seconds the Model Class Generator will open:

[[File:GS01 Model Generator.png]]

'''Note:'''
* use the '...' icon in ''Source Folder'' to browse to the '''''src''''' folder of the project in the plug-ins sub-directory;
* ''Package Name'' is 'org.evenos.model';
* ''Table Name'' is 'EVE_%' to generate models for both tables;
* ''Entity Type'' is 'U' for User Maintained.

Refresh the project to see the newly generated model classes.

=='M' Classes==
Create two 'M' classes to hold the business logic for each of the two tables:

'''Right-click ''org.evenos.model'' > New > Class > Name: MEVEMain > Finish'''

Add two constructors and a generated serial version ID:
<pre>
package org.evenos.model;

import java.sql.ResultSet;
import java.util.Properties;

public class MEVEMain extends X_EVE_Main{

/**
*
*/
private static final long serialVersionUID = -4652910060540398746L;

public MEVEMain(Properties ctx, ResultSet rs, String trxName) {
super(ctx, rs, trxName);
// TODO Auto-generated constructor stub
}

public MEVEMain(Properties ctx, int EVE_Main_ID, String trxName) {
super(ctx, EVE_Main_ID, trxName);
// TODO Auto-generated constructor stub
}
}
</pre>

Repeat for '''''MEVESub''''':

<pre>
package org.evenos.model;

import java.sql.ResultSet;
import java.util.Properties;

public class MEVESub extends X_EVE_Sub{

/**
*
*/
private static final long serialVersionUID = -2076611601274220946L;

public MEVESub(Properties ctx, int EVE_Sub_ID, String trxName) {
super(ctx, EVE_Sub_ID, trxName);
// TODO Auto-generated constructor stub
}

public MEVESub(Properties ctx, ResultSet rs, String trxName) {
super(ctx, rs, trxName);
// TODO Auto-generated constructor stub
}
}
</pre>

To get some idea of what business logic is possible in these classes, look at the 'M' classes in the package 'org.compiere.model' in the project 'org.adempiere.base' which is the core of iDempiere.

==Dependencies==
The operation of the new plug-in is dependent on two other plug-ins, so use the '''Add...''' button to add 'org.adempiere.base' and 'org.adempiere.plugin.utils' to the plug-in manifest:

[[File:GS01 Manifest Dependencies.png]]

==Model Factory==
The plug-in requires a custom model factory to create the new class model instead of relying on the default model factory.
Create a new package <code>org.evenos.factories</code> with a new class <code>MyModelFactory</code>.

===iDempiere 9.0 onwards===

====Annotation Based Factory====

This type of model factory will automatically scan at runtime one or more packages searching for model classes with the <code>@Model</code> annotation. This annotation is added automatically by the Model Generator to all X classes.

<pre>
package org.evenos.factories;

import org.adempiere.base.AnnotationBasedModelFactory;

public class MyModelFactory extends AnnotationBasedModelFactory {

@Override
protected String[] getPackages() {
return new String[] {"org.evenos.model"};
}

}
</pre>

====Map Based Factory====

With this type of model factory one must declare for each table:

* Association between table name and its model class
* Model class instantiation for numeric identifier
* Model class instantiation via <code>ResultSet</code>

<pre>
package org.evenos.factories;

import org.idempiere.model.MappedModelFactory;

public class MyModelFactory extends MappedModelFactory {

public MyModelFactory() {
addMapping(MEVESub.Table_Name, () -> MEVESub.class
, (id, trxName) -> new MEVESub(Env.getCtx(), id, trxName)
, (rs, trxName) -> new MEVESub(Env.getCtx(), rs, trxName));
addMapping(MEVEMain.Table_Name, () -> MEVEMain.class
, (id, trxName) -> new MEVEMain(Env.getCtx(), id, trxName)
, (rs, trxName) -> new MEVEMain(Env.getCtx(), rs, trxName));
}

}
</pre>

===iDempiere 8.2 and earlier===

The following approach shows how to implement a model factory from scratch, without using the base classes available since iDempiere 9.0. Following code is also compatible with iDempiere 9.0.

<pre>
package org.evenos.factories;

import java.sql.ResultSet;

import org.adempiere.base.IModelFactory;
import org.compiere.model.PO;
import org.compiere.util.Env;
import org.evenos.model.MEVEMain;
import org.evenos.model.MEVESub;

public class MyModelFactory implements IModelFactory{

@Override
public Class<?> getClass(String tableName) {
if(tableName.equalsIgnoreCase(MEVESub.Table_Name))
return MEVESub.class;

if(tableName.equalsIgnoreCase(MEVEMain.Table_Name))
return MEVEMain.class;

return null;
}

@Override
public PO getPO(String tableName, int Record_ID, String trxName) {
if(tableName.equalsIgnoreCase(MEVESub.Table_Name))
return new MEVESub(Env.getCtx(), Record_ID, trxName);

if(tableName.equalsIgnoreCase(MEVEMain.Table_Name))
return new MEVEMain(Env.getCtx(), Record_ID, trxName);

return null;
}

@Override
public PO getPO(String tableName, ResultSet rs, String trxName) {
if(tableName.equalsIgnoreCase(MEVESub.Table_Name))
return new MEVESub(Env.getCtx(), rs, trxName);

if(tableName.equalsIgnoreCase(MEVEMain.Table_Name))
return new MEVEMain(Env.getCtx(), rs, trxName);

return null;
}
}
</pre>

==Component Definition==
The custom model factory must be made known to the OSGi framework so that it will be invoked in preference to the default model factory.

Create a new folder 'OSGI-INF' in the project and then create a Component Definition file:

'''Right-click ''OSGI-INF'' > New > Other... > Plug-in Development > Component Definition > Name: ModelFactory.xml > Finish'''

Enter the following:

[[File:GS01 OSGI-INF 0.png|920px]]

'''Note:'''
* ''Name'' is 'org.evenos.newwindow.model.factory'
* ''Class'' is 'org.evenos.factories.MyModelFactory' (use the Browse button to find it)
* Click on ''Add Property'' to create the 'service.ranking' property with type Integer and value 100 which will ensure that OSGi uses the custom model factory in preference to the default version

Now add IModelFactory to the list of Provided Services on the Services tab of the Component Definition:

'''Click 'Services' tab > Provided Services Add.. > IModelFactory''' and save the definition file.

Finally, update the Manifest so that the Component Definition loads every service defined in the OSGI-INF directory by changing the last line as follows:
<pre>
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Newwindow
Bundle-SymbolicName: org.evenos.newwindow
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Require-Bundle: org.adempiere.base;bundle-version="4.1.0",
org.adempiere.plugin.utils;bundle-version="4.1.0"
Service-Component: OSGI-INF/*
</pre>

'''Note:''' this last step is optional, but the presenter of the video recommends it as good practise.

The video includes a useful discussion on building business logic into the 'M' Classes [http://www.youtube.com/watch?v=F1lFHS2riG4&t=2433s at this point].

=Close-out=
The plug-in is now complete, so you can build the product and deploy it for use.

Main Page

2021-11-28T15:39:27Z

Sjg: Fixed stale links

[[Image:Lager_NortheastIndiana.png|400px|thumb|right|Example of a large warehouse]]
=News and Community =
{| style="border:0; margin: 0;" width="100%" cellspacing="10"
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#01DF01; border-bottom:1px solid #aaaaaa; text-align: center;">News</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:News-Paper.png|50px]]
| valign="top" |

==Other News==
'''December 2020,''' iDempiere 8.2 Stable Release. [https://www.idempiere.org/download/ Download your local copy] or [https://www.idempiere.org/test-sites/ Try it out online]<br>
'''October 2019,''' The biggest iDempiere World [http://conference.amprofession.eu/ Conference] was held in Lyon<br>
'''February 2018,''' SourceForge.net Commnuity Choice iDempiere [https://sourceforge.net/blog/february-2018-community-choice-project-month-idempiere/ Project of the Month]<br>
'''July 26th 2017,''' [https://blog.capterra.com/free-open-source-erp-software/ Capterra Logistics Technology Blog - “The Top 8 Free, Open Source ERP Software”]<br>
'''20th March 2017,''' [http://www.tgdaily.com/technology/10-best-open-source-software-in-2017 TG Daily - 10 Best Open Source Software in 2017]<br>
'''September 2016,''' - iDempiere wins again [http://www.infoworld.com/article/3122000/open-source-tools/bossie-awards-2016-the-best-open-source-applications.html#slide7 BOSSIE Award for 2nd year]<br>

<br><br><br>
==Available Plugins==
[[:Category:Available_Plugins|Available Plugins]]

==Let's Join Efforts==
[[Lets join efforts|Let's join efforts - starting point for joining efforts]]

==Chronology==
See [[Project:Current_events]] chronology
|}
</div>
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#01DF01; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:Community|'''Community''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Communication.png|50px]]
| valign="top" |
* [http://www.idempiere.org/ Main Landing Page]
* [http://groups.google.com/group/idempiere Googlegroup]
* [http://idempiere.atlassian.net/ JIRA Issue Tracker]
* [https://mattermost.idempiere.org Chatroom]
* [[Contributing to iDempiere]]
* [http://www.globalqss.com/wiki/index.php/IDempiere/Full_Meeting_Minutes Minutes of the weekly_meetings]
*[[:Category:Meetings|Annual Meetings]]
* [http://www.globalqss.com/wiki/index.php/IDempiere Carlos Ruiz]
* [https://hub.docker.com/r/idempiereofficial/idempiere Docker IDempiere Official]
|}
</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"

[[Image:Community-Berg.png|50px]]
* [http://twitter.com/idempiere Twitter for Code Updates]
* [http://www.facebook.com/groups/idempiere Facebook]
* [https://www.linkedin.com/grp/home?gid=5146317 LinkedIn]
* [https://en.wikipedia.org/wiki/IDempiere Wikipedia]
|}
</div>
|}
If no one is answering you maybe you need to know [http://www.catb.org/esr/faqs/smart-questions.html How To Ask Questions The Smart Way]

=Features=

{| style="border:0; margin: 0;" width="100%" cellspacing="10"
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#01DF01; border-bottom:1px solid #aaaaaa; text-align: center;">'''Functions'''</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" |

*[https://test.idempiere.org/ Demo Test].
** '''EMail''': ''admin @ gardenworld.com'' (including spaces!) '''Password''': ''GardenAdmin''
** '''EMail''': ''superuser @ idempiere.com'' OR ''system @ idempiere.com'' (including spaces!) '''Password''': ''System''

[http://en.wikipedia.org/wiki/Enterprise_resource_planning (ERP) Enterprise resource planning]

[http://en.wikipedia.org/wiki/Customer_relationship_management (CRM) Customer Relationship Management]

'''Third Party Plugins''' [[:Category:Available_Plugins| find here]]

'''Functions of iDempiere'''
* Multiple Organizations
* Multiple Client
* Multiple Languages
* Multible currency
* Multiple Accounting Formats and expandable

<br/>'''Securing iDempiere'''
* [https://wiki.idempiere.org/en/Securing_iDempiere Securing iDempiere Server]

<br/>'''Supported web browsers'''
* Firefox
* All browsers based on chromium (google chrome, opera, edge, brave, chromium)

|}
</div>

| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#01DF01; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:New Features|New Features Index]]</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" |

* [[:Category:New_Features_v9.1|Version 9.1]]
* [[:Category:New_Features_v8.2|Version 8.2]]
* [[:Category:New_Features_v7.1|Version 7.1]]
* [[:Category:New_Features_v6.2|Version 6.2]]
* [[:Category:New_Features_v5.1|Version 5.1]]
* [[:Category:New_Features_v4.1|Version 4.1]]
* [[:Category:New_Features_v3.0|Version 3.0]]
* [[:Category:New_Features_v2.1|Version 2.1]]
* [[:Category:New_Features_v2.0|Version 2.0]]
* [[:Category:New_Features_v1.0|Version 1.0]]

- - - - - - - - - - - - - - - - - - - - -
* [[:Category:New Features Architecture|'''A''' → Architecture]]
* [[:Category:New Features Development|'''D''' → Development]]
* [[:Category:New Features Functional‏‎|'''F''' → Functional]]
* [[:Category:New Features Security|'''S''' → Security]]
* [[:Category:New Features Technical‏‎|'''T''' → Technical]]
* [[:Category:New Features User Experience (Usability)|'''U''' → User Experience (Usability)]]

|}
</div>

| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#01DF01; border-bottom:1px solid #aaaaaa; text-align: center;">'''Server Requirements'''</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" |
| valign="top" |

'''Supported Platforms'''
* Linux
* Windows
* Mac
<br/>
'''System Requirements'''

* [https://openjdk.java.net/ Java OpenJDK >= 11]
* [http://www.postgresql.org/ PostgreSQL >= 9.6]
* or [http://www.oracle.com/us/products/database/overview/index.html?origref=http://www.idempiere.org/ Oracle]
|}</div>
|}

=[[:Category:User_Manual|User's Manual for iDempiere]]=

{| style="border:0; margin: 0;" width="100%" cellspacing="10"
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:Installation|'''Installation:''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_mProcess.png|50px]]
| valign="top" |

[[:Category:Installation|'''Installation:''']]

* [[:Category:Installation Windows‏‎|Installation Windows‏]]
* [[:Category:Installation Linux|Installation Linux (Debian, Ubuntu, etc.)]]
* [[:Category:Installation Database|Installation Database]]
* [[:Category:Installation Eclipse|Installation Eclipse]]
* [[:Category:Installation Installer|Installation Installer]]
* [[:Category:Installation Development Prerequisites|Installation Development Prerequisites]]
* Installation [[Translations|language Pack]] / [[Localizations]]
* [[:Category:Docker|Docker installation and configuration]]

'''Integration points'''
*iDempiere has several integration points to integrate with other systems. The built in integration points are:

* Configurable and flexible CSV-import
* [[Web services]]
* JMS messaging

|}
</div>
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">'''iDempiere Basics'''</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Ok24.png|50px]]
| valign="top" |

'''Basics'''
*[[:Category:Reference Manual|Reference Manual]]
*[[Login Help|Login Help]]
*[[Reference|Menu Tree of ClientAdmin]]
*[[Reference-System|Menu Tree of System]]
*[[:Category:HowTo-Functional|HOW TOs Functional]]
*[[:Category:Diagramms-and_Overviews|Diagrams and overviews]]

|}
</div>
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:System administration|'''System administration:''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Preference24.png|50px]]
| valign="top" |

[[:Category:System administration|'''System administration:''']]

* [[:Category:System settings|System settings]]
* [[:Category:Client‏‎|Client administration]]
* [[:Category:Organization‏‎|Organization administration]]
* [[:Category:Role‏‎|Role administration]]
* [[:Category:User‏‎|User administration]]
* [[:Category:HowTo-Technical|HOW TOs Technical]]

|}</div>
|}

{| style="border:0; margin: 0;" width="100%" cellspacing="10"
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:Business_Partner‏‎|'''Business Partner''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_BPartner24.png|50px]]
| valign="top" |

*[[:Business Partner Manual‏‎]]
*[[:Category:Business Partner base data|Business Partner base data‎]]

|}
</div>
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:Materials management‏‎|'''Materials management''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Product24.png|50px]]
| valign="top" |
[[:Category:Materials management base data‏‎|'''Materials management base data:''']]

* [[:Category:Article base data‏‎|Article base data]]
** [[:Category:Price List‏‎|Price List]]
* [[:Category:Warehouse base data‏‎|Warehouse base data]]

[[:Category:Consisted movements‏‎|'''Consisted movements:''']]
* [[:Category:Consisted movements‏‎|Consisted movements]]
* [[:Category:Physical Inventory‏‎|Physical Inventory]]

'''Performance Analysis'''
* Storage Detail
|}
</div>
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:Procurement‏‎|'''Procurement''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Info24.png|50px]]
| valign="top" |

[[:Category:Procurement‏‎|'''Procurement:''']]

* [[:Category:Procurement announcement‏‎|Procurement announcement]]
* [[:Category:Purchase Order‏‎|Purchase Order]]
* [[:Category:Material Receipt‏‎|Material Receipt]]
* Receipt Confirm
* Invoice (supplier)
* [[Match Order and Invoice]]
|}</div>
|}

{| style="border:0; margin: 0;" width="100%" cellspacing="10"
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">'''Sales and Marketing'''</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Payment24.png|50px]]
| valign="top" |

[[:Category:Sales‏‎|'''Sales...''' ]]

* [[:Category:Marketing Campaign‏‎|Marketing Campaign]]
* [[:Category:Distribution base data‏‎|Distribution base data]]
* [[:Category:Sales request‏‎|Sales request]]
* [[:Category:Sales order‏‎|Sales order]]
* [[:Category:Shipments‏‎|Shipments]]
* [[:Category:Sales invoice‏‎|Sales invoice]]
* [[:Category:RMA‏‎|Returns RMA]]
* [[:Category:Expenditure distribution‏‎|Expenditure distribution]]
* [[:Category:Project‏‎|Project]]
* [[:Category:Delivery note‏‎|Delivery note]]

|}
</div>
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">'''Manufacturing Management'''</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Prod.png|50px]]
| valign="top" |

'''Engineering Management'''

* Resource Manufacturing
* Manufacturing Workflow

'''Planning Management'''

* Product Planning
* Forecast Management
* Material Requirement Planning
* Capacity Requirement Planning
* Distribution Ressource Planning

[[:Category:Production‏‎|'''Production Mangement''']]

'''Distribution Management'''

[[:Category:Quality‏‎|'''Quality Management''']]

'''Standard Costing Management'''
|}
</div>

| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#D0E2EE; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:Financial accounting‏‎|'''Financial accounting''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em 0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Calculator24.png|50px]]
| valign="top" |

'''[[Accounting basics]]'''

[[:Category:Financial accounting‏‎|'''Financial accounting:''']]
* [[:Category:Financial accounting base data‏‎|Financial accounting base data]]
** [[:Category:Account‏‎|Account]]
** [[:Category:Currency‏‎|Currency]]
** [[:Category:Tax administration‏‎|Tax administration]]
** [[:Category:Bank Cashbook‏‎|Bank Cashbook]]

* [[:Category:Property and equipment‏‎|'''Property and equipment''']]
** [[:Category:Depreciation/amortization‏‎‏‏‎|Depreciation/amortization]]

* [[:Category:Accounting|Accounting]]
** [[:Category:Open items|Open items]]
** [[:Category:Payments|Payments]]
** [[:Category:Financial reports‏‎|Financial reports]]
** [[:Category:Performance measurement‏‎|Performance measurement]]
** [[:Category:Cost accounting‏‎|Cost accounting]]
*** [[Costing]]
*** [[Landed cost]]

* [[:Category:Staff|Staff]]
** [[:Category:Staff base data|Staff base data]]
|}</div>

|}

=[[:Category:Reference Manual|Develop iDempiere]]=

{| style="border:0; margin: 0;" width="100%" cellspacing="10"
| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#ECE5CA; border-bottom:1px solid #aaaaaa; text-align: center;">'''Documentation'''</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Wikiicon.jpg|50px]]
| valign="top" |

'''Wiki Basics'''

* [[WIKI history, development and statistics|WIKI history, development and statistics]]
* [[Conventions_Used_in_the_Documentation|Conventions Used in the Documentation]]
* [[Set_up_Category|Set up Category]]
* [http://meta.wikimedia.org/wiki/Help:Contents This is a list of guides and single-topic help files for the MediaWiki ]

|}
</div>

| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#ECE5CA; border-bottom:1px solid #aaaaaa; text-align: center;">'''Translation'''</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Translate24.png|50px]]
| valign="top" |

'''Translation into other languages '''

* [[Translation_Project|Translation Project]]
* [http://wiki.idempiere.org/wiki/Main_Page Edit language package]
* [[:es:Guia_de_Migración_de_Módulos|Sample work in Spanish]] and [[:de:Anleitung_zur_Migration_von_Modulen|German]]

|}
</div>

| valign="top" style="padding:0; border:1px solid #aaaaaa; margin-bottom:5px;" |
<div style="font-size: 105%; padding:0.4em; background-color:#ECE5CA; border-bottom:1px solid #aaaaaa; text-align: center;">[[:Category:Development|'''Development''']]</div>
<div style="background:#ffffff; padding:0.2em 0.4em;">
{| style="border: 0; margin: 0;" cellpadding="3"
| valign="top" | [[Image:Icon_Preference24.png|50px]]
| valign="top" |

'''Programming iDempiere'''
* [https://github.com/idempiere/ Source code repository]
* [https://jenkins.idempiere.org/ Jenkins Continuous Build Server]
* [[Contributing_to_Trunk|Contributing to Core]]
* [[:Category:Plug-In Development|Plug-In Development Guide]]
* [https://web.archive.org/web/20200919013831/http://red1.org/adempiere/viewtopic.php?f=29&t=1713 How to create plugin] with a sample module migrated to iDempiere.
* [[Database structure]]
* [[:Category:HowTo-Technical|HOW TOs Technical]]
* [[:Category:Code Scratchpad|Code Scratchpad]]
* [https://web.archive.org/web/20200919013831/http://red1.org/adempiere/viewtopic.php?f=29&t=1713 Module Migration Guide] - learning how to Pack Out, Create Plugin, PackIn, Migrate legacy module script.
* [[Creating reports using JasperReports]]
* [[Create a custom document class]]

|}</div>
|}

=iDempiere vs others ERPs=
* [https://web.archive.org/web/20200919013831/http://red1.org/adempiere/viewtopic.php?f=33&t=1482 Future of iDempiere by '''red1''']
* [http://techytony.wordpress.com/2013/06/29/idempiere-vs-adempiere-usability-round-1/ iDempiere vs ADempiere Usability Round 1]
* [http://techytony.wordpress.com/2013/07/05/idempiere-adempiere-usability-on-the-homepage/ iDempiere, ADempiere Usability on The Homepage]

=Update iDempiere Server=
==Release 8.2==
* Update your iDempiere server:
cd /opt/idempiere-server # change to the home where you installed iDempiere
bash update.sh https://jenkins.idempiere.org/job/iDempiere8.2/ws/org.idempiere.p2/target/repository/
bash sign-database-build-alt.sh

* After that you can update your database with this script:
cd utils; bash RUN_SyncDB.sh
# if RUN_SyncDB.sh throws error, review the problem, fix it and run it again until no errors are thrown

=License =

iDempiere is released under the terms of the [http://www.gnu.org/licenses/old-licenses/gpl-2.0.de.html GPL v2]. For more information, see the official site.

=Credits=
*[https://www.idempiere.org/contributors/ Contributors]
*[https://www.idempiere.org/sponsors/ Sponsors]

‏‎
[[Category: Table of contents]]
[[Category: general information about iDempiere]]

[[en:Main Page]]
[[es:Página_principal]]
[[de:Hauptseite]]
[[fr:Accueil]]
[[pt:Página_principal]]
[[da:Forside]]
[[el:Αρχική_σελίδα]]
[[nl:Hoofdpagina]]
[[pl:Strona główna]]
[[ru:Заглавная_страница]]
[[bg:Начална_страница]]
[[hu:Kezdőlap]]
[[sr:Главна_страна]]
[[sv:Huvudsida]]
[[tr:Ana_sayfa]]
[[ms:Laman_Utama]]
[[zh:首页]]
[[ja:メインページ]]
[[th:หน้าหลัก]]
[[id:Halaman_Utama]]
[[ar:الصفحة_الرئيسية]]
[[it:Pagina_principale]]
[[ro:Pagina_principală]]

Developing Plug-Ins - IModelFactory

2021-09-23T03:40:56Z

Sjg: /* AbstractModelFactory */

[[Category:Development|P]]
[[Category:Developer documentation‏‎]]
[[Category:Plug-In Development]]
__TOC__
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 ([[User:Jan.thielemann|Jan.thielemann]]) or write me [mailto:jan.thielemann@evenos.de 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.

=Prerequisites=
Before you start this tutorial, you should take a look at the follwing tutorials:
* [[Developing_plug-ins_without_affecting_the_trunk|Developing Plug-Ins without affecting the Trunk]]
* [[Developing_Plug-Ins_-_Get_your_Plug-In_running|Developing Plug-Ins - Get your Plug-In started]]
* [[Developing_Plug-Ins_-_ModelValidator|Developing Plug-Ins - ModelValidator]]

=tl;dr=
https://www.youtube.com/watch?v=Pxi46BmIrTw
https://www.youtube.com/watch?v=F1lFHS2riG4

=The workflow=
==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())

==IModelFactory==
'''NOTE: If you use Eclipse Oxigen or a newer version, you can use annotations instead of creating the component definition manually. Read more about it [[Developing_plug-ins_without_affecting_the_trunk#Event_handle|here]]'''

After creating the plug-in and setting its dependencies, click on File>New>Other... and select "Component Definition" from the Plug-in Development section.

[[File:Pluginmodelfactory1.png|320px]]

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.

[[File:Pluginmodelfactory2.png|320px]]

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:

[[File:Pluginmodelfactory3.png|320px]]

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.

[[File:Pluginmodelfactory4.png|320px]]

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).

[[File:Pluginmodelfactory5.png|320px]]

On the Services tab, add the IModelFactory to the "Provided Services" section.

[[File:Pluginmodelfactory6.png|320px]]

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()

[[File:Pluginmodelfactory7.png|320px]]

Make sure that your plug-in is active in the run configurations

[[File:Pluginmodelfactory8.png|320px]]

Start the client and make sure your plug-in is active

[[File:Pluginmodelfactory9.png|320px]]

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:

[[File:Pluginmodelfactory10.png|320px]]

==AbstractModelFactory==
It is encouraged that new model factories extend from [https://github.com/idempiere/idempiere/blob/master/org.adempiere.base/src/org/adempiere/base/AbstractModelFactory.java AbstractModelFactory] as it takes care of most of the common tasks assigned to model factories.

Please note that this class was added to the iDempiere 9 codebase.

==AnnotationBasedModelFactory==
This is the new default model factory that can be used/extended from iDempiere plugins. It detects model classes automatically as long as they have the @Model annotation. Model classes with M prefix don't have to be annotated, as long as their X classes (discussed above) are annotated. The default model generator (discussed below) was also modified in order to annotate X classes automatically.

[[File:Annotated Model Factory.png|561px|Sample AnnotationBasedModelFactory implementation]]

This code snippet shows how to implement a model factory on a plugin by extending AnnotationBasedModelFactory. Implementing classes are encouraged to indicate what are the packages where they model classes are located, by overriding the ''getPackages'' method.

[https://github.com/idempiere/idempiere/blob/master/org.adempiere.base/src/org/adempiere/base/AnnotationBasedModelFactory.java AnnotationBasedModelFactory] was added as part of the iDempiere 9 codebase.

==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

=Troubleshooting=
*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")

[[ja:IModelFactoryのプラグイン開発]]

Developing Plug-Ins - IModelFactory

2021-09-23T03:39:40Z

Sjg: Brief description of new model factories

[[Category:Development|P]]
[[Category:Developer documentation‏‎]]
[[Category:Plug-In Development]]
__TOC__
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 ([[User:Jan.thielemann|Jan.thielemann]]) or write me [mailto:jan.thielemann@evenos.de 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.

=Prerequisites=
Before you start this tutorial, you should take a look at the follwing tutorials:
* [[Developing_plug-ins_without_affecting_the_trunk|Developing Plug-Ins without affecting the Trunk]]
* [[Developing_Plug-Ins_-_Get_your_Plug-In_running|Developing Plug-Ins - Get your Plug-In started]]
* [[Developing_Plug-Ins_-_ModelValidator|Developing Plug-Ins - ModelValidator]]

=tl;dr=
https://www.youtube.com/watch?v=Pxi46BmIrTw
https://www.youtube.com/watch?v=F1lFHS2riG4

=The workflow=
==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())

==IModelFactory==
'''NOTE: If you use Eclipse Oxigen or a newer version, you can use annotations instead of creating the component definition manually. Read more about it [[Developing_plug-ins_without_affecting_the_trunk#Event_handle|here]]'''

After creating the plug-in and setting its dependencies, click on File>New>Other... and select "Component Definition" from the Plug-in Development section.

[[File:Pluginmodelfactory1.png|320px]]

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.

[[File:Pluginmodelfactory2.png|320px]]

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:

[[File:Pluginmodelfactory3.png|320px]]

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.

[[File:Pluginmodelfactory4.png|320px]]

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).

[[File:Pluginmodelfactory5.png|320px]]

On the Services tab, add the IModelFactory to the "Provided Services" section.

[[File:Pluginmodelfactory6.png|320px]]

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()

[[File:Pluginmodelfactory7.png|320px]]

Make sure that your plug-in is active in the run configurations

[[File:Pluginmodelfactory8.png|320px]]

Start the client and make sure your plug-in is active

[[File:Pluginmodelfactory9.png|320px]]

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:

[[File:Pluginmodelfactory10.png|320px]]

==AbstractModelFactory==
It is encouraged that new model factories extend from [https://github.com/idempiere/idempiere/blob/master/org.adempiere.base/src/org/adempiere/base/AbstractModelFactory.java AbstractModelFactory] as as it takes care of most of the common tasks assigned to model factories.

Please note that this class was added to the iDempiere 9 codebase.

==AnnotationBasedModelFactory==
This is the new default model factory that can be used/extended from iDempiere plugins. It detects model classes automatically as long as they have the @Model annotation. Model classes with M prefix don't have to be annotated, as long as their X classes (discussed above) are annotated. The default model generator (discussed below) was also modified in order to annotate X classes automatically.

[[File:Annotated Model Factory.png|561px|Sample AnnotationBasedModelFactory implementation]]

This code snippet shows how to implement a model factory on a plugin by extending AnnotationBasedModelFactory. Implementing classes are encouraged to indicate what are the packages where they model classes are located, by overriding the ''getPackages'' method.

[https://github.com/idempiere/idempiere/blob/master/org.adempiere.base/src/org/adempiere/base/AnnotationBasedModelFactory.java AnnotationBasedModelFactory] was added as part of the iDempiere 9 codebase.

==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

=Troubleshooting=
*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")

[[ja:IModelFactoryのプラグイン開発]]

File:Annotated Model Factory.png

2021-09-23T03:30:44Z

Sjg:

Sample implementation of AnnotationBasedModelFactory from an iDempiere plugin.

Setting up Eclipse

2021-06-10T19:21:32Z

Sjg: Updated Eclipse setup for iDempiere 8.2

<font size=-2>
⇐
[[Installing_iDempiere|Table of Contents]] |
[[Download the Code]] |
Setting up Eclipse |
[[Importing DB Seed Manually]]
⇒
</font>

== Materialize and build ==

On the operating system navigate to the folder where you cloned the code, named below as $IDEMPIERE_REPOSITORY (f.e. /home/carlos/sources/idempiere), and run the next command:
cd $HOME/sources/idempiere
mvn verify
This command download all libraries on Bundle-ClassPath, build all projects and output binaries to org.idempiere.p2/target/products. If not, verify with mvn -version that maven is using the correct java-version.

== Setup workspace in Eclipse ==

* Open again the eclipse you configured with the workspace pointing to the folder where you cloned the code
** Following the example here this folder would be $HOME/sources/idempiere
* Turn off Project > Build automatically
* Navigate to Window > Preferences > General > Workspace
** set "Text file encoding" to "UTF-8" (if default is different)
** set "New text file line delimiter" to "Unix" (if default is different)
* Navigate to Window > Preferences > Java > Compiler
** set Java > Compiler > Compiler compliance level to "11"
* in Java > Installed JREs add the java-11-openjdk JRE if not present and select it as the active JRE:
** click the Add button, then
** select Standard VM, click next
** enter "/usr/lib/jvm/java-11-openjdk-amd64" as JRE Home, click finish
** click the Checkbox next to the new entry to apply the changes.
* Not required, is a personal preference, but normally I switch here to Java perspective and choose to Working Sets as the Top Level Elements

== Import projects in Eclipse ==

* Navigate to File > Import
* Navigate to Maven > Existing Maven Projects
* Click Next button and Browse to $IDEMPIERE_REPOSITORY (must appear there by default)
** Following the example here this folder would be $HOME/sources/idempiere
* All projects must appear selected, click Finish to complete the import
** At the end all projects are loaded into workspace
* Sometimes eclipse creates changes to the workspace, you can discard those changes at this point via right click on the projects and choosing Replace With > HEAD Revision

== (just for 8.2) Import target platform ==

These steps are required if you work on 8.2, but not required with the current master branch (a.k.a. 8.2.z)
* Still in eclipse
* Navigate to File > Import
* Navigate to General > Existing Projects into Workspace
* Click Next button and Browse to $IDEMPIERE_REPOSITORY/org.idempiere.p2.targetplatform
* Click Finish to complete the import

== Set target platform ==

* Now open the file org.idempiere.p2.targetplatform.target within the project org.idempiere.p2.targetplatform
** This is the default target platform definition with remote url
** Here eclipse takes some time downloading the required dependencies, you can prepare some Colombian coffee and wait patiently :)
* At Target Editor, click the "Set as Active Target Platform" link
* Wait for Eclipse to finish downloading bundles onto target platform
** Click the "Reload" button if some download fail, until there are not red errors on the Locations list

* At the end you can enabled back Project > Build automatically
* In case there are files with compilation errors you can right click on the iDempiere project and select Maven > Update Projects, then press OK

''This tutorial is brought to you by [[User:CarlosRuiz|Carlos Ruiz]] from [https://www.bx-service.com/ BX Service GmbH]. Feel free to improve directly or suggest using the Discussion tab.

[[Category:User Manual|I]]
[[Category:Installation|E]]
[[Category:Installation Eclipse]]
[[Category:Development‏‎]]
[[Category:Developer documentation‏‎]]


<font size=-2>
⇐
[[Installing_iDempiere|Table of Contents]] |
[[Download the Code]] |
Setting up Eclipse |
[[Importing DB Seed Manually]]
⇒
</font>