Best Practice Bookmarks - (PostgreSQL / Java / Spring / Hibernate)

Some best practices that are useful in this stack.

Contents:

PostgreSQL
Java
Spring / Hibernate
Security
REST
Testing
Git
Other
Stack

PostgreSQL

"To address these difficulties, we recommend using date/time types that contain both date and time when using time zones. We do not recommend using the type time with time zone (though it is supported by PostgreSQL for legacy applications and for compliance with the SQL standard)".
- https://www.postgresql.org/docs/current/static/datatype-datetime.html#DATATYPE-TIMEZONES
Further reading for date/time types:
- http://blog.untrod.com/2016/08/actually-understanding-timezones-in-postgresql.html
- http://phili.pe/posts/timestamps-and-time-zones-in-postgresql/
- http://justatheory.com/computers/databases/postgresql/use-timestamptz.html => (Good summary for best practices)
Always use timezone names like "Europe/Istanbul". Never ever use offsets! Timezone names do take care of daylight savings etc.
- http://blog.untrod.com/2016/08/actually-understanding-timezones-in-postgresql.html
Always use timestamptz when possible. Use timestamp when there is no other way.
- http://justatheory.com/computers/databases/postgresql/use-timestamptz.html
A possible way of inserting into timestamptz when you don't know the offset at a given time and timezone. But this should be your last resort. Note that +0000 value is not being taken into account since the type is timestamp. You add that +0000 offset value to make it compatible with Java's OffsetDateTime.

INSERT INTO test2 (tested_at) VALUES (TIMEZONE('Europe/Istanbul', '2018-03-05 17:35:24+0000'::timestamp));
You get the offset manually by the below link:
- https://www.timeanddate.com/worldclock/converter.html
You can still use AT TIME ZONE (or TIMEZONE()) when querying. It's useful for conversions between timezones.
- http://justatheory.com/computers/databases/postgresql/use-timestamptz.html
- http://phili.pe/posts/timestamps-and-time-zones-in-postgresql/#converting-between-timezones

A great section to understand the difference between timestamp and timestamptz. It also descirebes the logic behind the data type changes when doing time zone conversions. Basically you don't just convert timezones, you also convert an absolute point in time to a specific local time in a given timezone.
- http://phili.pe/posts/timestamps-and-time-zones-in-postgresql/#converting-between-timezones
- https://stackoverflow.com/questions/31962786/why-does-postgres-discard-timezone-information-with-at-time-zone (Similar question, no answer)

"The function timezone(zone, timestamp) is equivalent to the SQL-conforming construct timestamp AT TIME ZONE zone."
- https://www.postgresql.org/docs/current/static/functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT
timestamptz is always displayed at according to the TIMEZONE setting of the db session such as TIMEZONE='UTC'. You can set the default value through postgresql.conf. The rest is up to the application which may be overridden (via anything like Spring, Hibernate, SQL client etc).
- http://justatheory.com/computers/databases/postgresql/use-timestamptz.html
You can get the client timezone and offset from ios, Android and javascript. Even if none of these help, you can still use TimeZone class in Java to get the offset by the date and timezone. So the above conversion from timestamp to timestamptz in PostgreSQL is not necessary.
Two great sql style guides (or naming conventions) are below. First one seems derived by PostgreSQL: (Note: schemas should be named with underscores _ too. Link below:)
You can also use JPQL instead of SQL. (You can also use none of the querying languages since Spring Data JPA automatically creates repository implementtions by method name conventions.) A JPQL intro:
- https://www.thoughts-on-java.org/jpql/
It seems that adding "created_at" and "updated_at" columns are still common in database design:
As soon as there are examples of simple codes (or codenames) as primary keys, I'm gonna go for it. Saves a lot of work/time in development and much more elegant. One of the links suggest that the terms is called abbreviated encoding or Celko's encoding. But there is one more thing. It should be kept as small as possible, 3 characters at most (for performance reasons.)
UPDATE: A great alternative is postgresql's enum:
- https://www.postgresql.org/docs/current/static/datatype-enum.html
The choice between UUID vs Auto Increment really depends on the application. Some people defend UUID, dismiss auto-increment and some people do the opposite. There is no consensus on this topic. Some argumentation here:
In my opinion, the choice between soft delete vs hard delete really depends on the column. If it is a user table, then yes. Soft delete makes a lot of sense. But if it is like a "record" column in "jogtracker" application then hard delete should be sufficient. There is no reason to store incorrect rows inserted by the user itself. There is a lot of debate as usual on this topic.
- https://stackoverflow.com/questions/378331/physical-vs-logical-soft-delete-of-database-record (Second answer is great.)
- http://abstraction.blog/2015/06/28/soft-vs-hard-delete (Nice comparison)
- http://udidahan.com/2009/09/01/dont-delete-just-dont/ (Advocating soft delete)
- http://jameshalsall.co.uk/posts/why-soft-deletes-are-evil-and-what-to-do-instead (Advocating hard delete)
- https://www.thoughts-on-java.org/implement-soft-delete-hibernate/ (Soft delete Hibernate implementation - might be useful though)
The recommended timestamp format is "yyyy-MM-dd HH:mm:SS+tz" (ISO 8601). Ex:
- https://www.postgresql.org/docs/current/static/datatype-datetime.html#DATATYPE-DATETIME-INPUT

  2004-10-19 10:23:54+02

Db schema name conventions are similar to the tables.
If the table name is a reserved word in Postgresql just try to find a different name. This is what many people do to avoid clashes.
- https://stackoverflow.com/questions/22256124/cannot-create-a-database-table-named-user-in-postgresql
- https://dba.stackexchange.com/questions/198907/how-should-we-name-tables-that-resembles-with-reserved-words
Max char length for email is 320. Therefore, an email field in a db should be varchar(320)
- https://tools.ietf.org/html/rfc3696
The max output length for bcrypt is 60 characters. Therefore, password field should be varchar(60)
- https://stackoverflow.com/questions/5881169/what-column-type-length-should-i-use-for-storing-a-bcrypt-hashed-password-in-a-d
On the char types of postgresql:

There is no performance difference among these three types, apart from increased storage space when using the blank-padded type, and a few extra CPU cycles to check the length when storing into a length-constrained column. While character(n) has performance advantages in some other database systems, there is no such advantage in PostgreSQL; in fact character(n) is usually the slowest of the three because of its additional storage costs. In most situations text or character varying should be used instead. - https://www.postgresql.org/docs/current/static/datatype-character.html

Java

Changing between different java versions:
- https://blogs.oracle.com/pranav/switch-between-different-jdk-versions-in-windows
- http://makble.com/jdk-8-and-cprogramdataoraclejavajavapath => This is the recent one
Packaging by features instead of layers is the common practice:
This item is a note to self. Service methods shouldn't have the same name as dao methods. Ex:
- recordService.create
- recordService.list
- recordService.update
- recordService.getRecordById => This is wrong
- recordService.delete
- recordService.getReport => This method can also be changed as "report"
As you can see above "get" would be much more elegant instead of "getRecordById". Standard REST service endpoints should have standard method names. Same goes with "getReport".
DAO classes should be named as xxxRepository. I found this convention by coincidence while checking JHipster:
- http://gist.asciidoctor.org/?github-mraible/jhipster4-demo//README.adoc
All the classes should be package-private except the beans. Beans should be public otherwise it may cause runtime error on spring. All the members should be private if possible. If not, then the access privilege should be defined according to the usage:
- https://docs.oracle.com/javase/tutorial/java/javaOO/accesscontrol.html
- https://stackoverflow.com/questions/215497/in-java-difference-between-package-private-public-protected-and-private
Some naming conventions for MVC objects:
- Entity => User
- Data transfer object => UserDTO or UserModel. (UserDTO is much more common in Java world.)
- Data acess object => UserDAO or UserRepository
- Service interface => UserService
- Service Implementation => AbstractUserService or UserServiceImpl (UserServiceImpl is much more common in Spring world.)
- May need references here.
Throw IllegalArgumentException when a parameter is missing.
- https://stackoverflow.com/questions/2517965/what-exception-to-throw-when-an-important-parameter-dependency-is-missing

Spring / Hibernate

"The @Transactional annotation is metadata that specifies that an interface, class, or method must have transactional semantics". It still needs to be tested to see if I use it correctly:
- https://docs.spring.io/spring/docs/5.0.2.RELEASE/spring-framework-reference/data-access.html#transaction-declarative-attransactional-settings
JPA is Java Persistence API and Hibernate is JPA provider. JPA has only java interfaces but not its implementations whereas Hibernate has implementations of those interfaces. Spring Data JPA is a JPA Data Access Abstraction. Spring Data offers a solution to GenericDao custom implementations. It can also generate JPA queries on your behalf through method name conventions. All the annotations in regarding the data layer on Java comes from JPA. Hibernate exists in this jar: spring-boot-starter-data-jpa
If import.sql is found in the classpath, Hibernate will load it automatically.
- https://www.mkyong.com/spring-boot/spring-boot-spring-data-jpa-oracle-example/
- https://docs.spring.io/spring-boot/docs/current/reference/html/howto-database-initialization.html
Typically, your repository interface will extend Repository, CrudRepository, JPARepository or PagingAndSortingRepository in Spring Data JPA.
- https://www.mkyong.com/spring-boot/spring-boot-spring-data-jpa-oracle-example/
- https://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories
Below links detail the differences between JPARepository, PagingAndSortingRepository, CrudRepository. Basically, JPARepository > PagingAndSortingRepository > CrudRepository > Repository and they all extend each other respectively. That being said JPARepository is the biggest one containing all the methods.
- https://stackoverflow.com/questions/14014086/what-is-difference-between-crudrepository-and-jparepository-interfaces-in-spring
- http://www.baeldung.com/spring-data-repositories
There are three ways to implement a complete where clause on a dynamic level:
1. As in jogtracker that you just replace the operator and direclty send the whole clause to sql query. But this may be open to sql injection attacks and you must be careful on that.
2. Using RQSL, but it does not seem like it's a standart yet and you should use a third party library which is not widely adopted by the community. Here are the links:
3. The third and most appropriate way is to use Spring Data JPA Specifications. Related article is below:
  - http://www.baeldung.com/rest-api-query-search-or-operation
Some discussion on JPA entities.
- https://stackoverflow.com/questions/6033905/create-the-perfect-jpa-entity
Exception handling should be done via ControllerAdvice annotation in Spring cause it provides a more centralized approach which leads to a much cleaner code. Jogtracker also uses ControllerAdvice annotations. One of the below links also provide a great example for a json response output of a rest api error:
Rest apis can be documented either by using external tools like swagger (which is one of the most popular) or Spring Rest Docs. Since Spring is our framework for doing most of the work, we will rely on this for now. Below is further reading and Spring Rest Docs resources. Additionally you can also create documentation by Postman now. Postman looks like it's progressed a lot by the time:
Spring REST Docs is chosen over swagger in general. Below are the links. But what about Postman?
I think below article is the best for rest api versioning that also includes spring fw. There is nowhere else from here to go. It includes everything. Depending on your needs you can choose which way you want from the list below:
- http://www.springboottutorial.com/spring-boot-versioning-for-rest-services
"We generally recommend that you locate your main application class in a root package above other classes. The @EnableAutoConfiguration annotation is often placed on your main class, and it implicitly defines a base “search package” for certain items. For example, if you are writing a JPA application, the package of the @EnableAutoConfiguration annotated class will be used to search for @Entity items. Using a root package also allows the @ComponentScan annotation to be used without needing to specify a basePackage attribute. You can also use the @SpringBootApplication annotation if your main class is in the root package."
- https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-structuring-your-code.html
It is possible to generate JPA entity classes from tables by using Eclipse (WTP), Hibernate, Oracle Enterprise Plugin for Eclipse etc. But it is not necessary now, since there a just a few classes and tables.
If you are using a sequential primary key with JPA (and Hibernate), you should define this sequence both in the code and db. Data type serial is enough for defining such a sequence in postgres. The Java code should look like this:

  @Id
  @SequenceGenerator(name="sequance_name", sequenceName="sequance_name", allocationSize=1)
  @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="sequance_name")
  private short id;

All the annotations above are important for the definition of the sequence otherwise it won't work, including the allocationSize. If you don't define the allocationSize the id value might go negative or collisions might happen.

When a not null field is defined in the db, normally you should be using both @NotNull and @Column(nullable = false) annotations. @NotNull annotation just checks POJO and @Column(nullable = false) annotation checks the db for null instances but Hibernate applies the bean validation constraints to DDL by default so @NotNull is enough in this case, thanks to the Hibernate.
Java Bean Validation API is the interface and the Hibernate Validator is the implementation. Since we use Spring and Hibernate is the default provider, importing @Email annotation from javax.validation.constraints.Email should be sufficient.
Below is a list of fundamental Hibernate annotations and lets you start from the get go.
- http://www.techferry.com/articles/hibernate-jpa-annotations.html
- https://auth0.com/blog/integrating-spring-data-jpa-postgresql-liquibase/
Core Spring annotations for your taste:
- http://www.techferry.com/articles/spring-annotations.html#ModelAttribute
The difference between @ModelAttribute and @RequestBody is defined below. @ModelAttribute is used for request params whereas @Requestbody is used for JSON/XML data in the request for REST services. Therefore @RequestBody is what we need.
- https://stackoverflow.com/questions/21824012/spring-modelattribute-vs-requestbody
- https://stackoverflow.com/questions/43716767/spring-mvc-requestbody-vs-modelattribute
Some examples of Spring bean scopes with the @Scope annotation. Default and most used one is singleton.
- https://www.mkyong.com/spring/spring-bean-scopes-examples/
- http://www.baeldung.com/spring-bean-scopes
Default value for a column can be handled by the db so you don't need an additional annotation or code in the JPA layer. But if you really need to handle that in the code you can just set an initial value for the variable and that's it.
- https://stackoverflow.com/questions/197045/setting-default-values-for-columns-in-jpa
Soft delete can easily be achieved by a single @Where annotation of Hibernate. This annotation should be placed right in the beginning of the entity.
- https://stackoverflow.com/questions/19323557/handling-soft-deletes-with-spring-jpa
- https://dzone.com/articles/hibernate-where-clause
OffsetDateTime should be used to map PostgreSQL's timestamptz. That's the default data type to be used in Java 8 JDBC Driver. Timezone offset is also necessity in ZonedDateTime so it's meaningless to use it. OffsetDateTime is the exact match of timestamptz
- https://jdbc.postgresql.org/documentation/head/java8-date-time.html
- https://docs.oracle.com/javase/9/docs/api/java/time/ZonedDateTime.html
Change the default timezone settings by the below links. They include all the possible answers including JVM, Spring, Hibernate, Jackson etc.
If you use RepositoryRestResource in Spring Data Rest together with RestController then RestController overrides the methods.
- https://stackoverflow.com/questions/22824840/when-to-use-restcontroller-vs-repositoryrestresource (check comments.)
To return 404 http status for that do not exist, just throw ResourceNotFoundException:
- https://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest/webmvc/ResourceNotFoundException.html
Use ResourceNotFoundException together with Optional in Java 8. Repository methods return Optional values so orElseThrow method of Optional will work. accountRepository.findById(id).orElseThrow(ResourceNotFoundException::new);
- http://www.baeldung.com/java-optional
You can simply compile and run spring boot with one single gradle command and that is bootRun however you can't stop the application gracefully and kill the daemon. You can build the application without testing by .\gradlew build -x test command. Additionally, you can use spring-boot-devtools which automatically deploys the server when the classpath is changed. Finally you can write a single .bat file that contains both .\gradlew clean build -x test and .\java -jar .\build\libs\app.jar so that you can create the jar and start the app with one single command.
Below are the links for adding HATEOAS to your Spring Boot project. If you want to add only the self relation link then the Spring guide wll be enough. But if you want to add links to all resources of an entity then you might want to check the Baeldung article. HATEOAS creates some null values. They can be ignored in DTO classes by JsonIgnore annotations.
There is a great way of using a default value for timestamptz fields. Use the annotations @CreationTimestamp and @UpdateTimestamp.
- https://www.thoughts-on-java.org/persist-creation-update-timestamps-hibernate/
File (image) upload on spring:
- https://spring.io/guides/gs/uploading-files/
- http://www.mkyong.com/spring-boot/spring-boot-file-upload-example/
Some old stackoverflow questions tell that DTOs should be used for serialization instead of entities:

It's possible to use Projections as DTOs in Spring Data Rest.
- https://www.javabullets.com/spring-data-rest-projections/
- https://stackoverflow.com/questions/45401734/how-to-work-with-dto-in-spring-data-rest-projects

You can use ModelMapper as an alternative to BeanUtils.copyProperties in order to convert entities to DTOs.
- http://www.baeldung.com/entity-to-and-from-dto-for-a-java-spring-application
- https://auth0.com/blog/automatically-mapping-dto-to-entity-on-spring-boot-apis/
You can @PreAuthorize together with Spring Data Rest as below.
- https://www.javabullets.com/securing-spring-data-rest-preauthorize/
- https://www.javabullets.com/spring-security-spring-data-rest/
Below is a great series on Spring Data Rest in general:
- https://www.javabullets.com/category/spring-data-rest/
An amazing solution to map Java Enum with Postgres Enum by Hibernate. As the author has said "Works like a charm."
- https://stackoverflow.com/questions/27804069/hibernate-mapping-between-postgresql-enum-and-java-enum
- https://vladmihalcea.com/the-best-way-to-map-an-enum-type-with-jpa-and-hibernate/
"Use the returned instance for further operations as the save operation might have changed the entity instance completely." For repository classes.
- https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/repository/CrudRepository.html#save-S-

Security

Argon2 won the password hashing competitions, but due to Spring implementations we should stick to bcrypt for now. Argon2 might still need some time. Links below:
I did some research on authentication methods in REST and a lot of developers seem to misunderstand the concepts such as OAuth and JWT. The only approach that has been agreed upon is OpenID Connect on top of OAuth 2.0. But I still think that it might be an architectural overkill because either I have to use a third-party identity provider for authentication or implement it by myself. HMAC seems a reasonable approach for machine-machine communicationin REST with API keys and API secrets.
With a detailed research, now I understand why oauth should be used for any kind of API authentication and security. Here are the use cases that are applicable in our scenarios:
1. You can use OpenID Connect to consume a third pary API. For example, you can use Google OpenId Connect to consume Google APIs and reach Google Servers:
  - https://developers.google.com/identity/protocols/OAuth2
2. You can use Open Id Connect to use authentication as a service by third party identity providers. You can use Google Accounts of your users to authenticate to your APIs. Note: Auth0 is great for this way of authentication. Includes lots of identity providers.
3. You can entirely build an oauth server by yourself. If you own Resource Server, Authorization Server and Identity Provider, then this is the authentication method that you should use. Examples are Toptal entrance application and Lefolio. It's OK to use Resource Owner Password Credentials Grant in this case. Client Credentials Grant should be used for machine to machine communication.
4. For the details of ouath flows and grants check links below:
  - https://auth0.com/docs/api-auth/which-oauth-flow-to-use
  - https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2
In Spring Security with OAuth 2.0, an application can contain both Authorization Server and Resource Server. "A Resource Server (can be the same as the Authorization Server or a separate application) serves resources that are protected by the OAuth2 token."
- http://projects.spring.io/spring-security-oauth/docs/oauth2.html
These three articles are used to enable ssl in spring security:
To implement oauth on spring security there is an amazing article on Medium. The others are supplementary:
ResourceId in OAuth and JWT is useful when there are multiple resources and multiple resource servers. It is unnecessary work to add resourceIds if there are only one resource. Below links do not explain this but some links related with resource id usage:
Random 64 characters of hex is enough for signing JWT tokens a.k.a. signing-key:
- dwyl/hapi-auth-jwt2#48
- https://github.com/dwyl/learn-json-web-tokens
Implementing your custom security annotation filter is as easy as below:
- https://dreamix.eu/blog/java/implementing-custom-authorization-function-for-springs-pre-and-post-annotations
- https://docs.spring.io/spring-security/site/docs/current/reference/html/el-access.html#el-access-web-path-variables
@PreAuthorize is used to give access before the method is called. @PostAuthorize is used to give access according to the return value. @PreFilter is filtering the data before the method call, @PostFilter is filtering the data after the method is invoked.
- https://stackoverflow.com/questions/22093018/valid-use-case-for-postauthorize-and-postfilter-annotations
- https://docs.spring.io/spring-security/site/docs/current/reference/html/el-access.html#el-pre-post-annotations
There is a great article on DZone that shows how to build a SQL Injection prevention filter manually. It can also be added as a dependency. Even including the content as a util class is sufficient.
- https://dzone.com/articles/custom-annotation-in-java-for-sql-injection-safe-p
- https://github.com/rkpunjal/sql-safe-annotation-example
From the OAuth 2 specification, request to the token endpoint should be sent as a key value parameters not JSON.
- https://stackoverflow.com/questions/38165131/spring-security-oauth2-accept-json/
- https://tools.ietf.org/html/rfc6749#section-4.1.3
.jks files should not be stored in source repository.
- https://security.stackexchange.com/questions/100584/where-should-a-keystore-jks-be-stored-in-a-repository
Below articles are helpful on handling login failures and authentication events:

REST

The most common starting points for JSON:
- https://mvnrepository.com/artifact/org.json/json
- https://github.com/FasterXML/jackson
There is a consensus about RESTful APIs in the coomunity, except the API versioning. Here are links:
Further reading on REST:
- http://www.restapitutorial.com/resources.html
- https://github.com/RestCheatSheet
JSON properties should have camelCase as it is told in REST conventions. The below code sample from jogtracker is WRONG!

  @JsonProperty("id")
  private Integer recordId;

  @JsonProperty("user_id")
  private Integer userId;
	
  @JsonProperty("air_temp")
  private Double airTemp;
	
  @JsonProperty("rel_temp")
  private Double relTemp;

File (image) upload on REST:

Testing

You need to mock objects in order to do unit testing because you are depending on db objects in these type of applications. JMockit and Mockito are clearly winners but Mockito has much bigger usage and community. It's either JMockit or PowerMock + Mockito (aka PowerMockito).
Below articles shows how to test a system behind spring security oauth:
- http://www.baeldung.com/oauth-api-testing-with-spring-mvc
- https://spring.io/guides/gs/testing-web/
Below articles summarize the e2e testing:

Use @TestPropertySource annotation to override the values in application.properties. An example is below:
- https://stackoverflow.com/questions/32974432/spring-junit-testing-properties-file

Git

Below are different articles on git branching strategy. Will be discessed in detail later.

Other

Connection pools should be used to improve the performance and HikariCp seems to be the most obvious choice.
- http://www.baeldung.com/hikaricp
- https://dzone.com/articles/database-connection-pooling-in-java-with-hikaricp
Using either Guava or Apache Commons library is a good start for a Java project.
"Guava is a productivity multiplier for Java projects across the board: we aim to make working in the Java language more pleasant and more productive. The Guava project contains several of Google's core libraries that we rely on in our Java-based projects: collections, caching, primitives support, concurrency libraries, common annotations, string processing, I/O, and so forth." Use it when it's needed.
- https://github.com/google/guava
- https://github.com/google/guava/wiki/PhilosophyExplained
It seems like jcenter surpassed mavenCentral.
- https://stackoverflow.com/questions/24852219/android-buildscript-repositories-jcenter-vs-mavencentral
- https://jfrog.com/knowledge-base/why-should-i-use-jcenter-over-maven-central/
Lombok is a great tool for creating boilerplate code such as getters, setters and toString(), hashCode(), equals() methods. It is considered to be safe and supports Java 9.
Liquibase is a source / version control tool for database. Flyway is also an alternative to this tool and referenced by Spring Boot / Pivotal. No need for the jogtracker though, but may be necessary for bigger projects and production environments.

Stack

* Windows 10
* PostgreSQL 10.2
* Java 9
* Spring Boot 2.0.0
* Gradle 4.6
* Eclipse Oxygen.2
* DBeaver
* Git 2.16

johnsonlu / best-practices