2 Get Started

Gradle is used for build in this guide. Gradle build dependency and task configurations also serve as the guide for other build tools such as Maven.

Add cmobilecom maven repository in your build.gradle:

repositories {	
	jcenter()
	mavenCentral()
	
	
	maven {
		url "https://cmobilecom.com/maven/repository/release"
	}
	
}

Kotlin DSL:

repositories {
	jcenter()
	mavenCentral()

	
	maven(url="https://cmobilecom.com/maven/repository/release")
	
}

Artifacts:

cmobilecom-jpa-jdbc: access database by JDBC (Java SE/Jakarta EE).
cmobilecom-jpa-android: access android built-in sqlite database.
cmobilecom-jpa-jpql: JPQL parser that is needed only if JPQL is used.
cmobilecom-jpa-processor: enhancer, static metamodel generator and schema generator.

For example,

Java SE/Jakarta EE:

dependencies {
	implementation 'com.cmobilecom:cmobilecom-jpa-jdbc:2.2.2'
	runtimeOnly 'com.cmobilecom:cmobilecom-jpa-jpql:2.2.2'
}

Android:

dependencies {
	implementation('com.cmobilecom:cmobilecom-jpa-android:2.2.2@aar') {
		transitive = true
	}
	
	runtimeOnly 'com.cmobilecom:cmobilecom-jpa-jpql:2.2.2'
}

Kotlin DSL for Android:

dependencies {
	implementation("com.cmobilecom:cmobilecom-jpa-android:2.2.2@aar") {
		setTransitive(true)
	}

	runtimeOnly("com.cmobilecom:cmobilecom-jpa-jpql:2.2.2")
}

See build.gradle of the examples for detail.

Cmobilecom JPA has dependencies on bean validation, CDI(Context and Dependency Injection) and JTA API. If bean validation, CDI and/or JTA are not used, exclude them from runtime classpath. For Jakarta EE, exclude them from WAR or EAR.

dependencies {
	// Java SE
	implementation ('com.cmobilecom:cmobilecom-jpa-jdbc:2.2.2') {
		exclude group: 'jakarta.validation', module: 'jakarta.validation-api'
		exclude group: 'jakarta.enterprise', module: 'jakarta.enterprise.cdi-api'
		exclude group: 'jakarta.transaction', module: 'jakarta.transaction-api'
	}
	
	// Jakarta EE
	implementation ('com.cmobilecom:cmobilecom-jpa-jdbc:2.2.2') {
		exclude group: 'jakarta.persistence', module : 'jakarta.persistence-api'
		exclude group: 'jakarta.validation', module: 'jakarta.validation-api'
		exclude group: 'jakarta.enterprise', module: 'jakarta.enterprise.cdi-api'
		exclude group: 'jakarta.transaction', module: 'jakarta.transaction-api'
	}
	
	// Android
	implementation('com.cmobilecom:cmobilecom-jpa-android:2.2.2@aar') {
		transitive = true
	
		// android does not support bean validation, CDI and JTA
		exclude group: 'jakarta.validation', module: 'jakarta.validation-api'
		exclude group: 'jakarta.enterprise', module: 'jakarta.enterprise.cdi-api'
		exclude group: 'jakarta.transaction', module: 'jakarta.transaction-api'
	}

	// Android (Kotlin DSL)
	implementation("com.cmobilecom:cmobilecom-jpa-android:2.2.2@aar") {
		setTransitive(true)

		// android does not support bean validation, CDI and JTA
		exclude(group="jakarta.validation", module="jakarta.validation-api")
		exclude(group="jakarta.enterprise", module="jakarta.enterprise.cdi-api")
		exclude(group="jakarta.transaction", module="jakarta.transaction-api")
	}
}

EntityManagerFactory and EntityManager

EntityManagerFactory and EntityManager are created differently in different environments.

Java SE

For Java SE, create an EntityManagerFactory and EntityManager for one persistence unit as followings:

	import com.cmobilecom.jpa.Constants;
	...
	
	Map<String, Object> properties = new HashMap<String, Object>();

	// JDBC properties
	properties.put(Constants.JDBC_USER, "test");
	properties.put(Constants.JDBC_PASSWORD, "123456");
	properties.put(Constants.JDBC_URL, "jdbc:mysql://localhost:3306/jpa_example_db?useSSL=false");
	
	EntityManagerFactory emf = Persistence.createEntityManagerFactory("pu_name", properties);
	EntityManager em = emf.createEntityManager();

Database connection properties can be set in META-INF/persistence.xml or set at runtime. Properties set at runtime override those in META-INF/persistence.xml.

Jakarta EE

In Jakarta EE environment, EntityManagerFactory and EntityManager are created by CDI injection and managed by container. Inject an EntityManager into an application component as followings:

@Stateless
public class DataServiceBean { 
	@PersistenceContext(unitName="jpa_jakartaee_example")
	EntityManager em;
}

Android

For android, create an EntityManagerFactory and EntityManager for one persistence unit as followings:

	import com.cmobilecom.jpa.Constants;
	...
	
	Map<String, Object> properties = new HashMap<>();
	
	Context context = ...  // application context or activity
	properties.put(Constants.ANDROID_CONTEXT, context);
	properties.put(Constants.ANDROID_CONNECTION_URL, "android:sqlite:jpa_example_db");
	
	EntityManagerFactory emf = Persistence.createEntityManagerFactory("pu_name", properties);
	EntityManager em = emf.createEntityManager();

If android context property (Constants.ANDROID_CONTEXT) is set, android built-in sqlite database will be used.

The connection URL for android sqlite database is

	android:sqlite:databseName

Identifier Equality

IdClass and Embedded Id types must implement equals and hashCode methods for entity equality test.


    @Override
    public boolean equals(Object o) {
        ...
    }
    
    @Override
    public int hashCode() {
        ...
    }

If entity, embeddable or basic type is used as Map key, it must implement equals and hashCode methods.

Lazy Initialization

The fetch type of all the associations and element collections should be declared as LAZY to minimize the object graph to load. Lazy attributes will be initialized dynamically on demand even if its entity is detached and its associated entity manager is closed.

Connection Pooling

Configure a data source that supports connection pooling, and specify it in META-INF/persistence.xml. For example,

	<non-jta-data-source>data-source-JNDI-name</non-jta-data-source>
	<jta-data-source>data-source-JNDI-name</jta-data-source>

Examples

Download Cmobilecom-JPA examples for Android, Java SE and Jakarta EE from Cmobilecom.com. See README on how to build and run examples.

← Overview→ Static Metamodel GenerationFrames / No Frames