Drop support for handling JPA entities as variables

yanavasileva commented 1 year ago

Acceptance Criteria (Required on creation)

Remove JPA relevant source and test code (and dependencies) from engine, engine-spring, and spring-boot-starter where applicable
Add paragraph in the migration guide
An example (process engine plugin) exist as an alternative

Hints

Feature overview:
- engine offers support for handling JPA entities as variables.
- In engine-spring, SpringTransactionsProcessEngineConfiguration, the jpaEntityManagerFactory is registered to the sessionFactories so it can be used in Spring Context.
- Spring Boot Starter
- The starter offers a default JPA configuration (docs) that uses the jpaEntityManagerFactory to provide the feature in Starter context.
- The starter also offers custom JPA configuration, where users can define custom transaction manager (CAM-11923, docs)
Reasoning: Dropping this feature support will simplify the connection between engine, engine-spring, and spring-boot-starter modules and make easier adopting to Spring and Spring Boot versions. Example, when updating to Spring 6 / Spring Boot 3 mentioned classes above need to be migrated to the Jakarta domain.
Impressions: not so many users use the feature in spring boot. Forum/Jira search: https://camunda.slack.com/archives/C055X2FLSLC/p1684237866143159?thread_ts=1684217243.890629&cid=C055X2FLSLC

Links

Related to https://github.com/camunda/camunda-bpm-platform/issues/3445

Breakdown

[x] engine
- remove classes from org.camunda.bpm.engine.impl.variable.serializer.jpa
- remove JPAVariableTest and org\camunda\bpm\engine\test\standalone\jpa\camunda.cfg.xml configuration
[x] engine-spring
- remove SpringTransactionsProcessEngineConfiguration#initJPA, SpringEntityManagerSessionFactory
- remove test class and beans from org.camunda.bpm.engine.spring.test.jpa
- remove org/camunda/bpm/engine/spring/test/jpa/JPASpringTest-context.xml configuration file
- ~~consider refactor the package structure of engine-spring and introduce impl packages~~ - won't do
[x] spring-boot-starter
- remove CamundaJpaConfiguration, DefaultJpaConfiguration, JpaProperty and all relevant source and test code (incl. configuration)
[x] migration test exists
[x] upgrade documentation exists
[x] a JPA variable handling example exists. Hint: create a process engine plugin to register sessionFactories and variableSerializers configuration. Consider creating a separate ticket.

### Pull requests
- [ ] https://github.com/camunda/camunda-bpm-platform/pull/3468
- [ ] https://github.com/camunda/camunda-bpm-examples/pull/258
- [ ] https://github.com/camunda/camunda-docs-manual/pull/1475
- [ ] https://github.com/camunda/camunda-docs-static/pull/368
- [ ] https://github.com/camunda/camunda-bpm-platform/pull/3507

Dev2QA handover

[ ] Does this ticket need a QA test and the testing goals are not clear from the description? Add a Dev2QA handover comment

yanavasileva commented 1 year ago

Next steps: @toco-cam will reach out to the Camunda Champions for feedback of feature usage.

Then we can decide to schedule, prioritize either this or https://github.com/camunda/camunda-bpm-platform/issues/3445

yanavasileva commented 1 year ago

We received limited feedback regarding the JPA questions. Confirming the feature is not widely used.

Decision:

Proceed with dropping of the feature for the engine, engine-spring, and starter.
Keep the custom JPA configuration for the Spring Boot Starter.

yanavasileva commented 1 year ago

During implementation of a migration test (create JPA variables in 7.19, config process engine plugin, fetch and assert values in 7.20), the following exception is observed:

Stacktrace

15:43:01.762 [main] ERROR org.camunda.bpm.engine.context - ENGINE-16004 Exception while closing command context: Entity does not exist: org.camunda.bpm.qa.upgrade.variables.FieldAccessJPAEntity - 1: entity is null org.camunda.bpm.engine.exception.NullValueException: Entity does not exist: org.camunda.bpm.qa.upgrade.variables.FieldAccessJPAEntity - 1: entity is null at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45) at java.lang.reflect.Constructor.newInstance(Constructor.java:423) at org.camunda.bpm.engine.impl.util.EnsureUtil.generateException(EnsureUtil.java:398) at org.camunda.bpm.engine.impl.util.EnsureUtil.ensureNotNull(EnsureUtil.java:55) at org.camunda.bpm.engine.impl.util.EnsureUtil.ensureNotNull(EnsureUtil.java:50) at org.camunda.bpm.qa.upgrade.scenarios7190.variables.JPAEntityMappings.findEntity(JPAEntityMappings.java:128) at org.camunda.bpm.qa.upgrade.scenarios7190.variables.JPAEntityMappings.getJPAEntity(JPAEntityMappings.java:118) at org.camunda.bpm.qa.upgrade.scenarios7190.variables.JPAVariableSerializer.readValue(JPAVariableSerializer.java:96) at org.camunda.bpm.qa.upgrade.scenarios7190.variables.JPAVariableSerializer.readValue(JPAVariableSerializer.java:37) at org.camunda.bpm.engine.impl.persistence.entity.util.TypedValueField.getTypedValue(TypedValueField.java:105) at org.camunda.bpm.engine.impl.persistence.entity.VariableInstanceEntity.getTypedValue(VariableInstanceEntity.java:278) at org.camunda.bpm.engine.impl.core.variable.scope.AbstractVariableScope.getValueFromVariableInstance(AbstractVariableScope.java:151) at org.camunda.bpm.engine.impl.core.variable.scope.AbstractVariableScope.getVariable(AbstractVariableScope.java:137) at org.camunda.bpm.engine.impl.cmd.GetExecutionVariableCmd.execute(GetExecutionVariableCmd.java:62) at org.camunda.bpm.engine.impl.interceptor.CommandExecutorImpl.execute(CommandExecutorImpl.java:28) at org.camunda.bpm.engine.impl.interceptor.CommandContextInterceptor.execute(CommandContextInterceptor.java:110) at org.camunda.bpm.engine.impl.interceptor.ProcessApplicationContextInterceptor.execute(ProcessApplicationContextInterceptor.java:70) at org.camunda.bpm.engine.impl.interceptor.CommandCounterInterceptor.execute(CommandCounterInterceptor.java:35) at org.camunda.bpm.engine.impl.interceptor.LogInterceptor.execute(LogInterceptor.java:33) at org.camunda.bpm.engine.impl.interceptor.ExceptionCodeInterceptor.execute(ExceptionCodeInterceptor.java:55) at org.camunda.bpm.engine.impl.RuntimeServiceImpl.getVariable(RuntimeServiceImpl.java:342) at org.camunda.bpm.qa.upgrade.scenarios7190.variables.JpaEntitiesTest.shouldHandleJpaVariables(JpaEntitiesTest.java:64) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:498) at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:59) at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12) at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:56) at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17) at org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:26) at org.junit.rules.TestWatcher$1.evaluate(TestWatcher.java:61) at org.camunda.bpm.engine.test.ProcessEngineRule$1.evaluate(ProcessEngineRule.java:185) at org.junit.runners.ParentRunner$3.evaluate(ParentRunner.java:306) at org.junit.runners.BlockJUnit4ClassRunner$1.evaluate(BlockJUnit4ClassRunner.java:100) at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:366) at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:103) at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:63) at org.junit.runners.ParentRunner$4.run(ParentRunner.java:331) at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:79) at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:329) at org.junit.runners.ParentRunner.access$100(ParentRunner.java:66) at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:293) at org.junit.runners.ParentRunner$3.evaluate(ParentRunner.java:306) at org.junit.runners.ParentRunner.run(ParentRunner.java:413) at org.apache.maven.surefire.junit4.JUnit4Provider.execute(JUnit4Provider.java:365) at org.apache.maven.surefire.junit4.JUnit4Provider.executeWithRerun(JUnit4Provider.java:273) at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:238) at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:159) at org.apache.maven.surefire.booter.ForkedBooter.invokeProviderInSameClassLoader(ForkedBooter.java:384) at org.apache.maven.surefire.booter.ForkedBooter.runSuitesInProcess(ForkedBooter.java:345) at org.apache.maven.surefire.booter.ForkedBooter.execute(ForkedBooter.java:126) at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:418)

Therefore I tested manually that the scenario works:

Spring Boot Starter 7.19 write variables, restart, read variables
Spring Boot Starter 7.29 write variables, migrate to 7.20, add process engine plugin, start and read variables.

Decision: In order to make progress now, simplify the migration test:

Create JPA entities as variables in 7.19
Validate the variables exist in 7.20
Add TODO to check the migration test again as follow up if there's time.

yanavasileva commented 1 year ago

Dependency updates:

None.

Removed dependencies

None. openjpa and hibernate-jpa-2.0-api are test dependencies that still be used in the instance migration and old engine tests.

Added dependencies

None. commons-collections is a test transitive dependency to openjpa that I wanted to remove as dependency, so the license has been already checked (Apache 2).

camunda / camunda-bpm-platform