Home/Field Guide/OSGi & Java
CONCEPT 05
Service Builder and persistence
Model custom Java entities, transactions, service boundaries, and schema upgrades.
Read the generated layers
Service Builder generates persistence, models, and service scaffolding from service.xml. A typical build has an API module with public types and a service module with persistence and implementation. Run buildService after editing the model and regenerate interfaces after adding public methods in implementation classes. Keep custom logic in the intended *LocalServiceImpl and *ServiceImpl classes.
Local services are callable by code in the portal and commonly hold transactions and business logic. They are a trusted code boundary. Remote services or REST resources must enforce permissions explicitly. Use the platform’s resource permission patterns and verify scope before delegating to a local service. Include resource initialization and removal where the domain requires instance permissions.
Worked design
Suppose the Partner Hub has a regulated processing ledger that must record a state change and an audit row atomically. Define the ledger entity and suitable finders. Let one service operation perform both writes within its transaction. Do external delivery after commit using a durable, retryable mechanism. Test duplicate delivery, a write failure, and a denied caller. Use an explicit, database-enforced uniqueness strategy where duplicate rows would break the invariant.
Schema changes are release work
- Generate and inspect changes locally. Use versioned upgrade steps for data and schema in existing environments.
- Rehearse against representative data and check the module schema version. A field addition may also require a backfill and a rollout plan.
- Use an external reference code or another durable business identifier for cross-environment integration where supported. Database IDs are installation-local.
- Inspect query and index performance. Exercise permission-filtered queries and avoid a per-record query loop.