4.2. Domain Layer Implementation¶
Caution
This version is already obsolete. Please check the latest guideline.
Index
- Roles of domain layer
- Flow of development of domain layer
- Implementation of Entity
- Implementation of Repository
- Implementation of Service
- Regarding transaction management
- Appendix
- Tips
4.2.1. Roles of domain layer¶
Domain layer implements business logicto be provided to the application layer.
Implementation of domain layer is classified into the following.
Sr. No. Classification Description
This guideline recommends the structure of creating Entity classes and Repository for the following reasons.
- By splitting the overall logic into business logic (Service) and the logic to access business data, the implementation scope of business logic gets limited to the implementation of business rules,
- Access logic to business data is standardized by consolidating the operations of business data in the Repository.
Note
Though this guideline recommends a structure to create Entity classes and Repository, it is not mandatory to perform development in this structure.
Decide a structure by taking into account the characteristics of the application as well as the project (structure of development team and development methodology).
4.2.2. Flow of development of domain layer¶
Sr. No. Team in-charge Description Warning
A system having a large development scope is often developed by assigning the application to multiple teams. In that case, it is strongly recommended to provide a common team to design Entity classes and Repository.
When there is no common team, O/R Mapper(MyBatis, etc.) should be called directly from Service and a method to access business data should be adopted without creating Entity classes and Repository .
4.2.3. Implementation of Entity¶
4.2.3.1. Policy of creating Entity class¶
Sr. No. Method Supplementary java.util.List<E>orjava.util.Set<E>.The Entity corresponding to the FK destination table is called as the related Entity in this guideline.java.lang.Stringrather than as an Entity.enumclass corresponding to code value should be created and it must be defined as property.
Warning
When table is not normalized, check whether to use the method of creating the Entity classes and Repository by considering the following points. Since the unnormalized tables do not have good compatibility with JPA, it is better not to use JPA.
The method of creating Entity classes and Repository is recommended; however, the characteristics of the application as well as the project (structure of development team and development methodology) must also be taken into account.
Note
If you want to operate business data as application, and as normalized Entity even if the tables are not normalized, it is recommended to use MyBatis as an implementation of RepositoryImpl of the infrastructure layer.
MyBatis is the O/R Mapper developed to map the SQL with object and not to map the database table record with object. Therefore, mapping to the object independent of table structure is possible depending on the implementation of SQL, .
4.2.3.2. Example of creating Entity class¶
4.2.3.2.1. Table structure¶
The table structure is as given below:
Sr. No. Classification Table name Description
4.2.3.2.2. Entity structure¶
If Entity classes are created with the help of policy defined by the above table, it results into the following structure.
Sr. No. Class name Description OrderItemandOrderCouponare stored as the related Entity.Itemis stored as the related Entity.Couponis stored as the related Entity.Categoryare stored as the related Entity. The association betweenItemandCategoryis done using m_item_category table.
As it can be observed from the above entity diagram, it might first seem that Order class is the only main entity class in the shopping site application; however, there are other main entity class as well other than Order class.
Below is the classification of main Entity classes as well as Entity class which are not main.
The following 4 Entities are treated as the main Entity for creating shopping site application.
Sr. No. Entity class Reasons for treating as the main Entity.
The following are not main Entities for creating shopping site application.
Sr. No. Entity class Reason of not treating Entity as main Entity
4.2.4. Implementation of Repository¶
4.2.4.1. Roles of Repository¶
Repository has following 2 roles.
- To provide to Service, the operations necessary to control Entity lifecycle (Repository interface).The operations for controlling Entity lifecycle are CRUD operations.
- To provide persistence logic for Entity (implementation class of Repository interface).Entity object should persist irrespective of the lifecycle (start and stop of server) of application.Mostly relational database is the permanent destination of Entity. However, NoSQL database, cache server, external system and file (shared disk) can also be the permanent destination.The actual persistence processing is done using O/R Mapper API.This role is implemented in the RepositoryImpl of the infrastructure layer. Refer to Implementation of Infrastructure Layer for details.
4.2.4.2. Structure of Repository¶
Repository consists of Repository interface and RepositoryImpl and performs the following roles.
Sr. No. Class(Interface) Role Description
Note
Is it possible to hide 100% of persistence platform dependent logic from the Service class ?
In some cases it cannot be hidden completely due to constraints of persistence platform and the libraries used to access the platform. As much as possible, platform dependent logic should be implemented in RepositoryImpl instead of Service class. When it is difficult to exclude the platform dependent logic and merits of doing so are less, persistence platform dependent logic can be implemented as a part of business logic (Service) process.
A specific example of this is given here. There are cases when unique constraints violation error is needed to be handled when save method of
org.springframework.data.jpa.repository.JpaRepositoryinterface provided by Spring Data JPA is called. In case of JPA, there is a mechanism of cache entity operations and SQL is executed when transactions are committed. Therefore, since SQL is not executed even if save method of JpaRepository is called, unique constraints violation error cannot be handled in logic. There is a method (flush method) to reflect cached operations as means to explicitly issue SQLs in JPA. saveAndFlush and flush methods are also provided in JpaRepository for the same purpose. Therefore, when unique constraints violation error needs to be handled using JpaRepository of Spring Data JPA, JPA dependent method (saveAndFlush or flush) must be called.Warning
The most important purpose of creating Repository is not to exclude the persistence platform dependent logic from business logic. The most important purpose is to limit the implementation scope of business logic (Service) to the implementation of business rules. This is done by separating the operations to access business data in Repository. As an outcome of this, persistence platform dependent logic gets implemented in Repository instead of business logic (Service).
4.2.4.3. Creation of Repository¶
Repository must be created using the following policy only.
Sr. No. Method Supplementary
4.2.4.4. Example of creating Repository¶
4.2.4.4.1. Structure of Repository¶
Entity class used in the explanation of Example of creating Entity class is used as an example, the resulting configuration is as follows:
4.2.4.5. Definition of Repository interface¶
4.2.4.5.1. Creation of Repository interface¶
An example of creating Repository interface is introduced below.
SimpleCrudRepository.java
This interface provides only simple CRUD operations.Method signature is created by referring toCrudRepositoryinterface andPagingAndSortingRepositoryprovided by Spring Data.public interface SimpleCrudRepository<T, ID extends Serializable> { // (1) T findOne(ID id); // (2) boolean exists(ID id); // (3) List<T> findAll(); // (4) Page<T> findAll(Pageable pageable); // (5) long count(); // (6) T save(T entity); // (7) void delete(T entity); }
Sr. No. Description java.util.Iterable. Here as a sample, it is set tojava.util.List.PageableandPageare the interfaces provided by Spring Data.
TodoRepository.java
An example of creating Repository of Todo Entity, which was created in tutorial, on the basis of
SimpleCrudRepositoryinterface created above is shown below.// (1) public interface TodoRepository extends SimpleCrudRepository<Todo, String> { // (2) long countByFinished(boolean finished); }
Sr. No. Description SimpleCrudRepositoryinterface are added in this interface.In this case, “Method for acquiring count of Todo entity objects for which specified tasks have been finished” is added.
4.2.4.5.2. Method definition of Repository interface¶
CrudRepository and PagingAndSortingRepository provided by Spring Data for the methods performing general CRUD operations.java.util.Collection or java.util.List) interfaces which can be handled in a better way in logic are better than java.lang.Iterable.
Sr. No. Types of methods Rules
Method for searching a single record
- Method name beginning with findOneByto indicate that this method fetches a single record that matches with the condition.
- In the method name after “findOneBy”, physical or logical name of the field used as search condition must be specified. Hence, the method name must be such that it becomes possible to estimate “the kind of entity that can be fetched using this method”.
- There must be an argument for each search condition. However, when there are many conditions, DTO containing all search conditions can be provided.
- Return value must be Entity class.
Method for searching multiple records
- Method name beginning with findAllByto indicate that this method fetches all the records that matches with the condition.
- In the method name after “findAllBy”, physical or logical name of the field used as search condition must be specified. Hence, the method name must be such that it becomes possible to estimate “the kind of entity that can be fetched using this method”.
- There must be an argument for each search condition. However, when there are many conditions, DTO containing all search conditions can be provided.
- Return value must be collection of Entity class.
Method for searching multiple records with pagination
- Method name beginning with findPageByto indicate that this method fetches pages that matches with the condition.
- In the method name after “findPageBy”, physical or logical name of the field used as search condition must be specified. Hence, the method name must be such that it becomes possible to estimate “the kind of entity that can be fetched using this method”.
- There must be an argument for each search condition. However, when there are many conditions, DTO containing all search conditions can be provided.
Pageableprovided by Spring Data should be the interface for pagination information (start position, record count, sort information).- Return value should be
Pageinterface provided by Spring Data.
Count related method
- Method name beginning with countBy to indicate that this method fetches count of Entities which matches with the condition.
- Return value must be long type.
- In the method name after “countBy”, physical or logical name of the field used as search condition must be specified. Hence, the method name must be such that it becomes possible to estimate “the kind of entity that can be fetched using this method”.
- There must be an argument for each search condition. However, when there are many conditions, DTO containing all search conditions can be provided.
Method for existence check
- Method name beginning with existsBy to indicate that this method checks the existence of Entity which matches with the condition.
- In the method name after “existsBy”physical or logical name of the field used as search condition must be specified. Hence, the method name must be such that it becomes possible to estimate “the kind of entity that can be fetched using this method”.
- There must be an argument for each search condition. However, when there are many conditions, DTO containing all search conditions can be provided.
- Return value must be boolean type.
Note
In case of methods related to update processing, it is recommended to construct methods in the same way as shown above. “find” in the method name above can be replaced by “update” or “delete”.
Todo.java(Entity)
public class Todo implements Serializable { private String todoId; private String todoTitle; private boolean finished; private Date createdAt; // ... }
TodoRepository.java
public interface TodoRepository extends SimpleCrudRepository<Todo, String> { // (1) Todo findOneByTodoTitle(String todoTitle); // (2) List<Todo> findAllByUnfinished(); // (3) Page<Todo> findPageByUnfinished(); // (4) long countByExpired(int validDays); // (5) boolean existsByCreateAt(Date date); }
Sr. No. Description
4.2.4.5.3. Creation of RepositoryImpl¶
Refer to Implementation of Infrastructure Layer for the implementation of RepositoryImpl.
4.2.5. Implementation of Service¶
4.2.5.1. Roles of Service¶
Service plays the following 2 roles.
- Provides business logic to Controller.Business logic consists of create, update, consistency check etc of business data as well as all the processes related to business logic.Create and update process of business data should be delegated to Repository(or O/R Mapper) and service should be limited to implementation of business rules.
Note
Regarding distribution of logic between Controller and Service
In this guideline, the logic to be implemented by Controller and Service should be as per the rules given below.
- For the data requested from the client, single item check and correlated item check is to be performed in Controller (Bean Validation or Spring Validator).
- Conversion processes (Bean conversion, Type conversion and Format conversion) for the data to be passed to Service, must be performed in Controller instead of Service.
- Business rules should be implemented in Service.Access to business data is to be delegated to Repository or O/R Mapper.
- Conversion processes (Type conversion and Format conversion) for the data received from Service (data to respond to the client), must be performed in Controller (View class etc).
- Declare transaction boundary.Declare transaction boundary when business logic is performing any operation which requires ensuring data consistency (mainly data update process).Even in case of logic that just read the data, often there are cases where transaction management is required due to the nature of business requirements. In such cases, declare transaction boundary.Transaction boundary must be set in Service layer as a principle rule. If it is found to be set in application layer (Web layer), there is a possibility that the extraction of business logic hasnot been performed correctly.
Refer to Regarding transaction management for details.
4.2.5.2. Structure of Service class¶
@Service annotation is defined as Service or SharedService class.
Sr. No. Class Role Notes related to dependency relationship
Service class
- It is prohibited to call a method of Service class from another Service class method (Figure 1-1).For shared logic, create SharedService class.
- Method of Service class can be called from multiple Controllers (Figure 1-2). However, it must be created for each controller when processing is to be branched based on the calling controller.In such a scenario, create a method in SharedService class and call that method from the individual Service class methods.
2 SharedService class
- Methods of other SharedService classes can be called from a SharedService (Figure 2-1). However, Calling hierarchy should not become complicated. If calling hierarchy becomes complicated, there is a risk of reduction in maintainability.
- Methods of SharedService classes can be called from Controller (Figure 2-2). However, it can be only be done if there is no problem from transaction management perspective.If there is a problem from transaction management perspective, first create a method in Service class and implement transaction management in this method.
- It is prohibited to call methods of Service class from SharedService (Figure 2-3).
4.2.5.2.2. Reason for prohibiting the calling of other Service classes from Service class¶
Sr. No. Situations that can occur
4.2.5.2.3. Regarding interface and base classes to limit signature of method¶
Note
In large scale development, there are situations where not every single developer is highly skilled or situations like having consistency in development of business logic considering maintainability after servicing. In such situations, limiting the signature through interfaces can be an appropriate decision.
In this guideline, we do not specifically recommended to create interface to limit signature; however, type of architecture must be selected on the basis of characteristics of the project. decide the type of architecture taking into account the project properties.
4.2.5.3. Patterns of creating service class¶
There are mainly 3 patterns for creating Service.
Sr. No. Unit Creation method Description
BLogic.The characteristics of the application if creating Service using this pattern are basically same as those when creating Service for each use case.However, in this case extracting shared logic out of business logic might get more difficult compared to creation of Service for each use-case (Pattern No. 2).In this guideline, pattern of creating Service for each event is not specifically recommended. However, in large scale development, creating Service using thispattern can be considered as one of the options with the view of having consistency in development style of business logic from maintainability point of view.Warning
The pattern of Service creation must be decided by taking into account the features of application to be developed and the structure of development team.
It is not necessary to narrow down to any one pattern out of the 3 indicated patterns. Creating Services using different patterns randomly should be avoided for sure; however, patterns can be used in combinations, if policy of usage of patterns in certain specific conditions has been well-thought decision and has been directed by the architect. For example, the following combinations are possible.
[Example of usage of patterns in combination]
- For the business logic very important to the whole application, create as SharedService class for each Entity.
- For the business logic to be processed for the events from the screen, create as Service class for each Controller.
- In the Service class for each controller, implement business logic by calling the sharedService as and when required.
Tip
BLogic is generated directly from design documents when using “TERASOLUNA ViSC”.
4.2.5.3.1. Image of Application development - Creating Service for each Entity¶
Following is the image of application development when creating a Service for each Entity.
Note
An example of a typical application in which a Service is created for each Entity is a REST application. REST application provides CRUD operations (POST, GET, PUT, DELETE of HTTP) for published resources on HTTP. Most of the times, the resources published on HTTP are business data (Entity) or part of business data (Entity), they have good compatibility with the pattern of creating Service for each Entity.
In case of REST application, most of the times, use-cases are also extracted on a “per Entity” basis. Hence, the structure is similar to the case when Service is created for on a “per use-case” basis.
Sr. No. Description
4.2.5.3.2. Image of Application development - Creating Service for each use case¶
Sr. No. Description Note
With an increase in the size of the use-cases, the development scope of a person increases. At such a point of time, it becomes difficult to divide the work of this use-case with other developers. In case of application which has to be developed by introducing a large number of developer at the same time, the use-case can be further split into finer use-cases and which can then be allocated to more number of developers.
Sr. No. Description Tip
In some projects, “group of use-cases” and “use-cases” are used in place of “use-case” and “processes” used in this guideline.
4.2.5.3.3. Image of Application development - Creating Service for each use event¶
Following is the image of application development when creating a Service(BLogic) for each event.
Sr. No. Description Note
With an increase in the size of the use-cases, the development scope of a person increases. At such a point of time, it becomes difficult to divide the work of this use-casewith other developers. In case of application which has to be developed by introducing a large number of developer at the same time, the use-case can be further split into finer use-cases and which can then be allocated to more number of developers.
Sr. No. Description
4.2.5.4. Creation of Service class¶
4.2.5.4.1. Methods of creating Service class¶
Below are the points to be taken care of while creating Service class.
- Creation of Service interface
public interface CartService { // (1) // omitted }
Sr. No. Description
Note
Merits from architecture perspective
- If interface is there, When using AOP, Dynamic proxies functionality of standard JDK is used. In case of no interface, CGLIB included in Spring Framework is used. In case of CGLIB there are certain restrictions like “Advice cannot be applied on final methods” etc. Refer to Spring Reference Documentfor details.
- It becomes easier to create a stub of business logic. When application layer and domain layer are developed in parallel using different development teams, stubs of Service are required. When there is a need to create stubs, it is recommended to have interface .
- Creation of Service class
@Service // (1) @Transactional // (2) public class CartServiceImpl implements CartService { // (3) (4) // omitted }<context:component-scan base-package="xxx.yyy.zzz.domain" /> <!-- (1) -->
Sr. No. Description base-packageattribute of <context:component-scan> element.In case of this example, all the classes in “xxx.yyy.zzz.domain” is registered in container.valueattribute should be specified as required.Refer to Information required for “Declarative transaction management” for details.Moreover, to understand the points to be noted when using@Transactionalannotation, it is advisable to confirm with “Regarding drawbacks of transaction management”.@Scopeannotation is also prohibited.
Note
Reason for adding @Transactional annotation to class
Transaction boundary is required only for the business logic that updates the database. However, it is recommended to apply the annotation at class level to prevent bugs due to skipped annotation. However, defining
@Transactionalannotation only at required places (methods which update the database) is also fine.Note
Reason to prohibit non-singleton scopes
- prototype, request, session are the scopes for registering bean that maintains state. Hence they must not be used in Service class.
- When scope is set to request or prototype, performance is affected as the bean generation frequency is high in DI container.
- When scope is set to request or session, it cannot be used in non Web applications (for example, Batch application).
4.2.5.4.2. Creation of methods of Service class¶
Below are the points to be taken care of while writing methods of Service class.
- Creation of method of Service interface
public interface CartService { Cart createCart(); // (1) (2) Cart findCart(String cartId); // (1) (2) }
- Creation of methods of Service class
@Service @Transactional public class CartServiceImpl implements CartService { @Inject CartRepository cartRepository; public Cart createCart() { // (1) (2) Cart cart = new Cart(); // ... cartRepository.save(cart); return cart; } @Transactional(readOnly = true) // (3) public Cart findCart(String cartId) { // (1) (2) Cart cart = cartRepository.findByCartId(cartId); // ... return cart; } }
Sr. No. Description @Transactionalannotation, it is advisable to confirm with “Regarding drawbacks of transaction management”.
Tip
Transaction definition of business logic for reference
When business logic for reference is to be implemented, by specifying
@Transactional(readOnly = true), instruction can be given to run the SQL under “Read-only transactions” for JDBC driver.The way of handling read-only transactions depends on the implementation of JDBC driver; hence, confirm the specifications of JDBC driver to be used.
Note
Points to be noted when using “Read-only transactions”
If it is set to “perform health check” when retrieving a connection from connection pool, “Read-only transactions” may not be enabled. For details on this event and to avoid the same, refer to About cases where “Read-only transactions” are not enabled.
Note
Transaction definition when a new transaction is required to be started
Set
@Transactional(propagation = Propagation.REQUIRES_NEW)to start a new transaction without participating in the transaction of the caller method.
4.2.5.4.3. Regarding arguments and return values of methods of Service class¶
The below points must be considered for arguments and return values of methods of Service class.
java.io.Serializable) must be used for arguments and return values of Service class.Typical arguments and return values of the methods are as follows.
- Primitive types (
int,long)- Primitive wrapper classes (
java.lang.Integer,java.lang.Long)- java standard classes (
java.lang.String,java.util.Date)- Domain objects (Entity, DTO)
- Input/output objects (DTO)
- Collection (implementation class of
java.util.Collection) of above types- void
- etc …
Note
Input/Output objects
- Input object indicates the object that has all the input values required for executing Service method.
- Output object indicates the object that has all the execution results (output values) of Service method.
If business logic(BLogic class) is generated using “TERASOLUNA ViSC” then, input and output objects are used as argument and return value of the of BLogic class.
Values that are forbidden as arguments and return values are as follows.
- Objects (
javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse,javax.servlet.http.HttpSession,org.springframework.http.server.ServletServerHttpRequest) which are dependent on implementation architecture of application layer (Servlet API or web layer API of Spring).- Model(Form, DTO) classes of application layer
- Implementation classes of
java.util.MapNote
Reason for prohibition
- If objects depending on implementation architecture of application layer are allowed, then application layer and domain layer get tightly coupled.
java.util.Mapis too generalized. Using it for method arguments and return values makes it difficult to understand what type of object is stored inside it. Further, since the values are managed using keys, the following problems may occur.
- Values are mapped to a unique key and hence cannot be retrieved by specifying a key name which is different from the one specified at the time of inserting the value.
- When key name has to be changed, it becomes difficult to determine the impacted area.
How to sharing the same DTO between the application layer and domain layer is shown below.
- DTO belonging to the package of domain layer can be used in application layer.
Warning
Form and DTO of application layer should not be used in domain layer.
4.2.5.6. Implementation of logic¶
Implementation in Service and SharedService is explained here.
Service and SharedService has implementation of logic related to operations such as data fetch, update, consistency check of business data and implementation related to business rules.
Example of a typical logic is explained below.
4.2.5.6.1. Operate on business data¶
Refer to the following for the examples of data (Entity) fetch and update.
- When using MyBatis3, Database Access (MyBatis3)
- When using JPA, Database Access (JPA)
4.2.5.6.2. Returning messages¶
Note
Regarding resolving message
In service, instead of the actual message the information required for building the message (message code, message insert value) is resolved.
Refer to the following for detailed implementation method.
4.2.5.6.3. Returning warning message¶
org.terasoluna.gfw.common.message.ResultMessages ) is provided as common library. When the class provided in common library- Creation of DTO
public class OrderResult implements Serializable { private ResultMessages warnMessages; private Order order; // omitted }
Implementation of method of Service class
Following is an example of implementation of displaying a warning message. The message is “Products may not be delivered together since the order includes products which are not available right now”.
public OrderResult submitOrder(Order order) { // omitted boolean hasOrderProduct = orderRepository.existsByOrderProduct(order); // (1) // omitted Order order = orderRepository.save(order); // omitted ResultMessages warnMessages = null; // (2) if(hasOrderProduct) { warnMessages = ResultMessages.warn().add("w.xx.xx.0001"); } // (3) OrderResult orderResult = new OrderResult(); orderResult.setOrder(order); orderResult.setWarnMessages(warnMessages); return orderResult; }
Sr. No. Description hasOrderProducttotrue.Orderobject and warning message are returned by storing objects in a DTO calledOrderResult.
4.2.5.6.4. Notifying business error¶
- When reservation date exceeds deadline while making tour reservation
- When the product is out of stock at the time of placing an order
- etc …
org.terasoluna.gfw.common.exception.BusinessException ) is provided as common library.Note
Reason for considering business exception as an unchecked exception
Since business exceptions need to be handled in controller class, they can be configured as checked exception. However in this guideline, it is recommended that business exception be subclass of unchecked exception (
java.lang.RuntimeException). By default, if there is a RuntimeException, transaction will be rolled back. Hence, doing this will prevent leaving a bug in the source-code due to inadequate settings of @Transactional annotation. Obviously, if settings are changed such that transaction rollbacks even in case checked exceptions, business exception can be configured as subclass of checked exceptions.
// omitted if(currentDate.after(reservationLimitDate)) { // (1) throw new BusinessException(ResultMessages.error().add("e.xx.xx.0001")); } // omitted
Sr. No. Description Business exception is thrown since reservation date is past the deadline at the time of making reservation.
Refer to Exception Handling for details of entire exception handling.
4.2.5.6.5. Notifying system error¶
- When master data, directories and files that should already exist, do not exist
- When a checked exception generated by a library method is caught and this exception indicates abnormal system state.
- etc …
org.terasoluna.gfw.common.exception.SystemException) is provided as common library.@Transactinal annotation is set to java.lang.RuntimeException by default.ItemMaster itemMaster = itemMasterRepository.findOne(itemCode); if(itemMaster == null) { // (1) throw new SystemException("e.xx.fw.0001", "Item master data is not found. item code is " + itemCode + "."); }
Sr. No. Description System exception is thrown since master data that should already exist does not exist. Example of case when system error is detected in logic）
Example that throws system exception while catching IO exception while copying the file is shown below.
// ... try { FileUtils.copy(srcFile, destFile); } catch(IOException e) { // (1) throw new SystemException("e.xx.fw.0002", "Failed file copy. src file '" + srcFile + "' dest file '" + destFile + "'.", e); }
Sr. No. Description
Note
Regarding handling of data access error
When data access error occurs in Repository and O/R Mapper while executing business logic, it is converted to subclass of
org.springframework.dao.DataAccessExceptionand thrown. Error can be handled in application layer instead of catching in business logic. However, some errors like unique constraints violation error should be handled in business logic as per business requirements. Refer to Database Access (Common) for details.
4.2.6. Regarding transaction management¶
Transaction management is required in the logic where data consistency must be ensured.
4.2.6.1. Method of transaction management¶
There are various transaction management methods. However, in this guideline, it is recommended to use “Declarative Transaction Management” provided by Spring Framework.
4.2.6.1.1. Declarative transaction management¶
In “Declarative transaction management”, the information required for transaction management can be declared by the following 2 methods.
- Declaration in XML(bean definition file).
- Declaration using annotation (@Transactional) (Recommended).
Refer to Spring Reference Document for the details on “Declarative type transaction management” provided by Spring Framework.
Note
Reason for recommending annotation method
- The transaction management to be performed can be understood by just looking at the source code.
- AOP settings for transaction management is not required if annotations are used and so XML becomes simple.
4.2.6.1.2. Information required for “Declarative transaction management”¶
@Transactional annotation for at class level or method level which are considered as target of transaction management and specify the information required for@Transactional annotation.Note
In this guideline, it is a prerequisite to use
@org.springframework.transaction.annotation.Transactionalannotation provided by Spring Framework.Tip
From Spring 4, it is possible to use
@javax.transaction.Transactionalannotation added from JTA 1.2.However, in this guideline, it is recommended to use an annotation of Spring Framework that can specify the information required for “Declarative transaction management” in a much more detailed way.
Following attributes can be specified if Spring Framework annotation is used.
NESTED(JDBC savepoint) as an attribute value of the propagation method of transaction (propagationattribute).- Isolation level of transaction (
isolationattribute)- Timeout period of transaction (
timeoutattribute)- Read-only flag of transaction (
readOnlyattribute)
Sr. No. Attribute name Description 1 propagation 2 isolation 3 timeout 4 readOnly 5 rollbackFor 6 rollbackForClassName 7 noRollbackFor 8 noRollbackForClassName
Note
Location to specify the @Transactional annotation
It is recommended to specify the annotation at the class level or method level of the class. Must be noted that it should not interface or method of interface. For the reason, refer to 2nd Tips of Spring Reference Document.
Warning
Default operations of rollback and commit when exception occurs
When rollbackFor and noRollbackFor is not specified, Spring Framework performs the following operations.
- Rollback when unchecked exception of (java.lang.RuntimeException and java.lang.Error) class or its subclass occurs.
- Commit when checked exception of (java.lang.Exception) class or its subclass occurs. (Necessary to note)
Note
Regarding value attributes of @Transactional annotation
There is a value attribute in
@Transactionalannotation. However, this attribute specifies which Transaction Manager to be used when multiple Transaction Managers are declared. It is not required to specify when there is only one Transaction Manager. When multiple Transaction Managers need to be used, refer to Spring Reference Document.Note
Default isolation levels of main DB are given below.
Default isolation levels of main DB are given below.
- Oracle : READ_COMMITTED
- DB2 : READ_COMMITTED
- PostgreSQL : READ_COMMITTED
- SQL Server : READ_COMMITTED
- MySQL : REPEATABLE_READ
Note
Cases where “Read-only transactions” are not enabled
A mechanism is provided to run SQL under “Read-only transactions” by specifying
readOnly = true; however, when all of the following conditions are satisfied, there will be a JDBC driver where “Read-only transactions” are not enabled.[Conditions to generate this event]
- Perform health check when retrieving a connection from connection pool.
- Disable ‘Auto commit’ of connection retrieved from connection pool.
- Use
DataSourceTransactionManagerorJpaTransactionManagerasPlatformTransactionManager. (This event does not occur when usingJtaTransactionManager).[JDBC driver where occurrence of this event is confirmed]
org.postgresql:postgresql:9.3-1102-jdbc41(JDBC 4.1 compatible JDBC driver for PostgreSQL 9.3)[Method to avoid this event]
In a case where “Read-only transactions” are not enabled, if
readOnly = trueis specified, it ends up carrying out the unnecessary processes. Therefore, it is recommended to execute the SQL under “Updatable transactions” even for the reference processes.Other methods to avoid this event are as follows:
- Do not perform health check when retrieving a connection from connection pool.
- Enable ‘Auto commit’ of the connection retrieved from connection pool. (Disable ‘Auto commit’ only when transaction management is required)
However, However, do not change the design for ‘health check’ and ‘auto commit’ to avoid this event.
[Remarks]
- Reproduction of this event is confirmed on PostgreSQL 9.3 and Oracle 12c. It is not performed on any other database and versions.
- In PostgreSQL 9.3,
SQLExceptionoccurs whenjava.sql.Connection#setReadOnly(boolean)method is called.- When SQL or API call of JDBC is logged in using log4jdbc,
SQLExceptionoccurred from JDBC driver is output to log with ERROR level.- SQL Exception occurred from JDBC driver is ignored by exception handling of Spring Framework. Hence, even though it is not an error as application behavior, the “Read-only transactions” is not enabled.
- Occurrence of this event is not confirmed in Oracle 12c.
[Reference]
When following log is output using log4jdbc, it will be treated as a case corresponding to this event.
date:2015-02-20 16:11:56 thread:main user: X-Track: level:ERROR logger:jdbc.audit message:3. Connection.setReadOnly(true) org.postgresql.util.PSQLException: Cannot change transaction read-only property in the middle of a transaction. at org.postgresql.jdbc2.AbstractJdbc2Connection.setReadOnly(AbstractJdbc2Connection.java:741) ~[postgresql-9.3-1102-jdbc41.jar:na] ...
4.2.6.1.3. Propagation of transaction¶
- Controller calls a method of Service class.
At this time, since started transaction does not exist, transaction is started using
TransactionInterceptor. TransactionInterceptorcalls the method of service class after starting the transaction.- Service class calls a method of
SharedService. This method is also under transaction control. At this time, though started transaction exists,TransactionInterceptorparticipates in the started transaction without starting a new transaction. TransactionInterceptorcalls the method under transaction control after participating in the started transaction.TransactionInterceptorperforms commit or rollback according to result of processing and ends the transaction.
Note
Reason for occurrence of org.springframework.transaction.UnexpectedRollbackException
When propagation method of transaction is set to “REQUIRED”, though there is only one physical transaction, internally Spring Framework creates transaction boundaries.
In case of above example, when a method of SharedService is called, a TransactionInterceptor is started which internally provides transaction control boundary at SharedService level.
Therefore, when an exception (which is set as target of rollback) occurs in SharedService method, status of transaction is set to rollback (rollback-only) by TransactionInterceptor.
This transaction now cannot be committed.
Going further, if the Service method tries to commit this transaction due to conflicting settings of rollback target exception between Service method and SharedShared method,
UnexpectedRollbackException is generated by Spring Framework notifying that there is inconsistency in transaction control settings. When UnexpectedRollbackException is generated, it should be checked that there is no inconsistency in rollbackFor and noRollbackFor settings.
- Controller calls a method of Service class. This method is under transaction control. At this time, since started transaction does not exist, transaction is started by
TransactionInterceptor(Hereafter, the started transaction is referred as “Transaction A”). TransactionInterceptorcalls the method of service class after transaction (Transaction A) is started.- Service class calls a method of
SharedServiceclass. At this time, though started transaction (Transaction A) exists, since propagation method of transaction is “REQUIRES_NEW”, new transaction is started byTransactionInterceptor. (Hereafter, started transaction is referred as “Transaction B”). At this time, “Transaction A” is interrupted and the status changes to ‘Awaiting to resume’. TransactionInterceptorcalls the method of SharedService class after Transaction B is started.TransactionInterceptorperforms commit or rollback according to the process result and ends the Transaction B. At this time, “Transaction A” is resumed and status is changed to Active.TransactionInterceptorperforms commit or rollback according to the process result and ends the Transaction A.
4.2.6.1.4. Way of calling the method which is under transaction control¶
- Way of calling the method which is under transaction control
- Way of calling the method which is not under transaction control
Note
In order to bring internal method calls under transaction control
It is possible to enable transaction control for internal method calls as well by setting the AOP mode to
"aspectj". However, if internal method call of transaction management is enabled, the route of transaction management may become complicated; hence it is recommended to use the default “proxy” for AOP mode.
4.2.6.2. Settings for using transaction management¶
The settings required for using transaction management are explained.
4.2.6.2.1. PlatformTransactionManager settings¶
PlatformTransactionManager.xxx-env.xml
Example of settings for managing the transaction using JDBC connection which is fetched from DataSource is given below.
<!-- (1) --> <bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> <property name="dataSource" ref="dataSource" /> </bean>
Sr. No. Description
Note
When transaction management (Global transaction management) is required for multiple DBs (Multiple resources)
- It is necessary to use
org.springframework.transaction.jta.JtaTransactionManagerand manage transactions by using JTA functionality provided by application server.- When JTA is to be used in WebSphere and Oracle WebLogic Server, a
JtaTransactionManagerwhich is extended for the application server is automatically set by specifying <tx:jta-transaction-manager/>.
Implementation class of PlatformTransactionManager provided by Spring Framework¶ Sr. No. Class name Description
java.sql.Connection).Use this class when MyBatis andJdbcTemplateis to be used.
javax.persistence.EntityTransaction).Use this class when JPA is to be used.
javax.transaction.UserTransaction).Use this class to manage transaction with resources (Database/Messaging service/General-purpose EIS(Enterprise Information System) etc.) using JTS (Java Transaction Service) provided by application server.When it is necessary to execute the operations with multiple resources in a single transaction, it is necessary to use JTA for managing transactions.
4.2.6.2.2. Settings for enabling @Transactional¶
@Transactional annotation is used.@Transactional annotation are explained.xxx-domain.xml
<tx:annotation-driven /> <!-- (1) -->
Sr. No. Description With use of <tx:annotation-driven> element in XML (bean definition file), transaction control gets enabled at the locations where @Transactionalannotation is used.
4.2.6.2.3. Regarding attributes of <tx:annotation-driven> element¶
Various attributes can be specified in <tx:annotation-driven> and default behavior can be customized.
xxx-domain.xml
<tx:annotation-driven transaction-manager="txManager" mode="aspectj" proxy-target-class="true" order="0" />
Sr. No. Attribute Description 1 transaction-manager Specify PlatformTransactionManagerbean. When omitted, bean registered with the name “transactionManager” is used.2 mode Specify AOP mode. When omitted, "proxy"is the default value."aspectj"can be also be specified. It is recommended to use"proxy".3 proxy-target-class Flag to specify whether proxy target is limited to class (this is valid only in case of mode=”proxy”). When omitted, it will be “false”.
- In case of false, if the target class has an interface, proxy is done using dynamic proxies functionality of standard JDK. When there is no interface, proxy is done using GCLIB functionality.
- In case of true, proxy is done using GCLIB function irrespective of whether interface is available or not.
4 order Order of Advice of AOP (Priority). When omitted, it will be “Last (Lowest priority)”.
4.2.7. Appendix¶
4.2.7.1. Regarding drawbacks of transaction management¶
Note
Since the article of IBM DeveloperWorks is an old article (year 2009), some of the content is different than the behavior when using Spring Framework 4.1.
Specifically, the contents of “Listing 7. Using read-only with REQUIRED propagation mode - JPA”.
From Spring Framework 4.1, when Hibernate ORM 4.2 or higher version is used as JPA provider, it has been improved so that instruction can be given to run the SQL under “Read-only transactions” for JDBC driver (SPR-8959).
The way of handling read-only transactions depends on the implementation of JDBC driver; hence, confirm the specifications of JDBC driver to be used.
4.2.7.2. Programmatic transaction management¶
In this guideline, “Declarative transaction management” is recommended. However, programmatic transaction management is also possible. Refer to Spring Reference Document for details.
4.2.7.3. Sample of implementation of interface and base classes to limit signature¶
- Interface to limit signature
// (1) public interface BLogic<I, O> { O execute(I input); }
Sr. No. Description
- Controller
// (2) @Inject XxxBLogic<XxxInput, XxxOutput> xxxBLogic; public String reserve(XxxForm form, RedirectAttributes redirectAttributes) { XxxInput input = new XxxInput(); // omitted // (3) XxxOutput output = xxxBlogic.execute(input); // omitted redirectAttributes.addFlashAttribute(output.getTourReservation()); return "redirect:/xxx?complete"; }
Sr. No. Description
To standardize process flow of business logic when a fixed common process is included in Service, base classes are created to limit signature of method.
- Base classes to limit signature
public abstract class AbstractBLogic<I, O> implements BLogic<I, O> { public O execute(I input){ try{ // omitted // (4) preExecute(input); // (5) O output = doExecute(input); // omitted return output; } finally { // omitted } } protected abstract void preExecute(I input); protected abstract O doExecute(I input); }
Sr. No. Description
Sample of extending base classes to limit signature is shown below.
- BLogic class (Service)
public class XxxBLogic extends AbstractBLogic<XxxInput, XxxOutput> { // (6) protected void preExecute(XxxInput input) { // omitted Tour tour = tourRepository.findOne(input.getTourId()); Date reservationLimitDate = tour.reservationLimitDate(); if(input.getReservationDate().after(reservationLimitDate)){ throw new BusinessException(ResultMessages.error().add("e.xx.xx.0001")); } } // (7) protected XxxOutput doExecute(XxxInput input) { TourReservation tourReservation = new TourReservation(); // omitted tourReservationRepository.save(tourReservation); XxxOutput output = new XxxOutput(); output.setTourReservation(tourReservation); // omitted return output; } }
Sr. No. Description