A REST accelerator library. It allows for creating CRUD Controller and express conditions in JSON notation

The available solutions on the net doesn't offer a powerful expressive way to declare the conditions.
A truly CRUD Controller, should offer:
1. a generic based version that does the heavy workload.
2. a fully customizable solution based on business requirements.
3. a robust expressive way of WHERE conditions.
4. isolate system entities from the application layer by using DTOs (input/output) for the API.

By using XRest, you will offer your project two benefits:

1. a fast way to make CRUD controller for entities. read more
   • /getOne ( condition can be passed )
     
   • /getMany ( condition can be passed )
     
   • /count ( condition can be passed )
     
   • /createOne
     
   • /createMany
     
   • /updateOne
     
   • /updateMany
     
   • /deleteOne
     
   • /deleteMany ( condition should be passed )
     
2. support CRUD API set with JSON where condition. read more

You can utilize (xrest cli) to scaffold your necessary code.

1. Java 17 or higher (Lebrica JDK is recommended here)
2. Maven 3.9.2 or higher
3. Spring Boot

Principally, XRest is supposed to work on any Sql-based database (PostgreSQL, MySql or Microsoft Sql Server).

1. In your Spring Boot project, add the following to the POM file:

<dependency>
    <groupId>io.github.sattinos</groupId>
    <artifactId>xrest</artifactId>
    <version>1.0.19</version>
    <exclusions>
        <!-- Exclude spring-boot-starter-data-jpa to avoid version conflict -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </exclusion>
        <!-- Exclude spring-boot-starter-web to avoid version conflict -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. make sure you add this configuration to tell Spring to scan for XRest components:

@Configuration
@ComponentScan(basePackages = "org.malsati.xrest")
public class ApplicationConfig {
}

1. Design your entity read more
2. Design CRUD endpoints DTOs read more
3. Write down your entity mapper interface read more
4. Design your repository read more
5. Write down you service class read more
6. Write your CRUD Controller read more

When designing your entity, you have two options:

1. Design your entity freely without any utilization of XRest base classes or interfaces. read more
2. Make use of the list of interfaces and base entities offered by XRest. read more

You can design your own entity without any constraints.

for example:

@NoArgsConstructor
@Data
@Entity
@Table(name = "Author")
public class Author {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    protected Long id;

    @Column(name = "full_name", unique = true)
    private String fullName;

    @Column(name = "birth_date")
    private LocalDate birthDate;
}

Notice that here no XRest base entities is used.

back to main steps

When coming to business requirements, Audit Info are of three types:

1. Creation info:
   • who created the entity
   • when it has been created
2. Update info:
   • who updated the entity
   • when it has been updated
3. Delete info: (soft delete only)
   • who deleted the entity
   • when it has been deleted

XRest offers a list of base classes to cover this:

CreateEntity: for entities that needs only creation info of the entity.

example:

@Data
@Entity
@Table(name = "City")
public class City extends CreateEntity {
    private String name;
    private String isoCode;
}

UpdateEntity: for entities that needs only update info of the entity.

example:

@Data
@Entity
@Table(name = "MessageItem")
public class MessageItem extends UpdateEntity {
    private String contents;
    private String senderName;
}

DeleteEntity: for entities that needs only delete info of the entity.

example:

@Data
@Entity
@Table(name = "Color")
public class Color extends DeleteEntity {
    private String rgbValue;
}

AuditEntity: for entities that needs creation info as well as update info.

example:

@Data
@Entity
@Table(name = "Report")
public class Report extends AuditEntity {
    private String title;
    private String content;
}

FullAuditEntity: for entities that needs all the audit information (creation, update and delete).

example:

@Data
@Entity
@Table(name = "Contract")
public class Contract extends FullAuditEntity {
    private String startDate;
    private String endDate;
}

back to main steps

Note: There are a list of Audit interfaces that are considered the contracts of auditing. They might be useful in some situations: CreationInfo UpdateInfo DeletionInfo IdentityInfo

When you want your entity to be soft-deleted, make sure you implement the interface: DeletionInfo.

CRUD operations will support Soft Delete automatically when you implement this interface.

If your entity doesn't implement this interface, Hard Delete will be chosen by XRest.

@Data
@AllArgsConstructor
@NoArgsConstructor
public class CreateOneAuthorInputDto {
    private String fullName;
    private LocalDate birthDate;
    private Collection<Long> bookIds;
}

@Data
@AllArgsConstructor
@NoArgsConstructor
public class CreateOneAuthorOutputDto extends CreateOneAuthorInputDto {
    private Long id;

    public CreateOneAuthorOutputDto(Long id, String fullName, LocalDate birthDate, Collection<Long> bookIds) {
        super(fullName, birthDate, bookIds);
        this.id = id;
    }
}

public class UpdateOneAuthorInputDto extends CreateOneAuthorOutputDto implements IdentityInfo<Long> {  
}

When writing your UpdateOneInputDto you need to implement the interface IdentityInfo so that XRest will know how to retrieve the ID of the entity. The ID of the entity is used by XRest to do basic validation before doing the actual update of the entity. This validation is common to all entities though.

public class GetOneAuthorOutputDto extends CreateOneAuthorOutputDto {
}

public class DeleteOneAuthorOutputDto extends UpdateOneAuthorInputDto {
}

It should inherit from IMapper

@Mapper(componentModel = "spring", nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
public interface AuthorMapper extends IMapper<Author,
        Long,
        CreateOneAuthorInputDto,
        CreateOneAuthorOutputDto,
        UpdateOneAuthorInputDto,
        DeleteOneAuthorOutputDto,
        GetOneAuthorOutputDto> {

    @Override
    @Mapping(source = "bookIds", target = "books")
    Author createOneInputDtoToEntity(CreateOneAuthorInputDto createOneAuthorInputDto);
    
    @Override
    @Named("createOne")
    @Mapping(source = "books", target = "bookIds")
    CreateOneAuthorOutputDto entityToCreateOneOutputDto(Author entity);
    
    @Override
    List<Author> createManyInputDtoToEntities(Iterable<CreateOneAuthorInputDto> createManyInputDto);
    
    @Override
    @IterableMapping(qualifiedByName = "createOne")
    List<CreateOneAuthorOutputDto> entitiesToCreateManyOutputDto(List<Author> entities);
    
    @Override
    @Mapping(source = "bookIds", target = "books")
    Author updateOneInputDtoToEntity(UpdateOneAuthorInputDto updateOneAuthorInputDto);
    
    @Override
    @Mapping(source = "books", target = "bookIds")
    DeleteOneAuthorOutputDto entityToDeleteOneOutputDto(Author entity);
    
    @Override
    List<DeleteOneAuthorOutputDto> entitiesToDeleteManyOutputDto(List<Author> entity);
    
    @Override
    @Mapping(source = "books", target = "bookIds")
    GetOneAuthorOutputDto entityToGetOneoutputDto(Author entity);

    default List<Book> mapBookIdsToBooks(Collection<Long> bookIds) {
        var books = new ArrayList<Book>(bookIds.size());
        for (Long id: bookIds) {
            books.add(new Book(id));
        }
        return books;
    }

    default List<Long> mapBooksToBookIds(Collection<Book> books) {
        var bookIds = new ArrayList<Long>(books.size());
        for (var book: books) {
            bookIds.add(book.getId());
        }
        return bookIds;
    }
}

Show me how (first case)
Show me how (second case)

back to main steps

Make sure you inherit from JpaRepository as well as JpaSpecificationExecutor :

public interface AuthorRepository extends JpaRepository<Author, Long>, JpaSpecificationExecutor<Author> {    
}

back to main steps

1. It should extend CrudServiceORM
2. In its constructor, it should inject the entity repository and the mapper you've created in previous steps.
3. Implement the validation methods validateCreateOneInput and validateUpdateOneInput if needed (optional)
4. Implement the hooks onPreCreateOne, onPreUpdateOne and onPreDeleteOne if needed (optional)

Show me how (first case)
Show me how (second case)

@Service
public class AuthorsService extends CrudServiceORM<
        Author,
        Long,
        CreateOneAuthorInputDto,
        CreateOneAuthorOutputDto,
        UpdateOneAuthorInputDto,
        DeleteOneAuthorOutputDto,
        GetOneAuthorOutputDto> {
    
    public AuthorsService(
            AuthorRepository authorRepository,
            AuthorMapper mapper) {
        super(authorRepository, mapper);
    }   
}

back to main steps

1. It should inherit from CRUDController
   
2. It should pass the service class you've created in previous step

@RequestMapping("/app/author")
@RestController
public class AuthorsController extends CrudController<Author,
        Long,
        CreateOneAuthorInputDto,
        CreateOneAuthorOutputDto,
        UpdateOneAuthorInputDto,
        DeleteOneAuthorOutputDto,
        GetOneAuthorOutputDto> {
    
    public AuthorsController(AuthorsService authorsService) {
        super(authorsService);
    }
}

back to main steps

mvn test

while testing the project, I recommend you test using the test runner of IntelliJ Idea Community Edition. Each test case will output explanatory messages. Run the tests from the Test Suite ContollersTestsSuite

It is a Spring Boot web app, that starts the journey with you:

1. How to Design an entity in both ways (utilize XRest Base classes, and freely design your entity).
2. Shows how to design DTO classes.
3. Shows how to write mapper.
4. Shows how to write your repository classes.
5. Shows how to write your custom service classes and write custom business validation rules as well as create/update/delete hooks.
6. Shows you the power of JSON Condition and how to pass it to the API.
7. Shows how to write your controller classes.
8. Shows how to form JSON Condition in case of relation (ONE-TO-ONE, ONE-TO-MANY, MANY-TO-MANY).

The test project test cases:

1. AuthorControllerTest it has 16 test cases. It shows how to utilize XRest base entities.
2. BookControllerTest it has 13 test cases. It show how your freely designed entities fit into XRest.
3. AuthorAndBookControllerTest it has 3 test cases mainly for how to deal with relation.

If you have further test cases that needs to be addressed, just drop me an email or open an issue.

The test project source code

The Where condition is in JSON notation. It allows you to express a business filter in JSON format. Whether you need this condition in the API, Service Layer or Infrastructure Layer.

The Structure: It can have one of these two forms:

1. LHS/RHS format:
{
    "op": ...,
    "lhs": ...,
    "rhs": ...        
}

This is used with Binary operators, where:
op: operator type ( <, =, <=, >, >=, !=, like )
lhs: left hand side, should be the entity field name.
rhs: right hand side, should be the value

example1:
{
    "op": "like",
    "lhs": "title",
    "rhs": "%Harry Potter%"
}
=> all entities which have a title similar to the form: %Harry Potter%

example2:
{
    "op": ">",
    "lhs": "age",
    "rhs": 18
}
=> all entities which have an age higher than 18

If the type of the rhs is not scalar, you need to provide a hint what is it through the "type" key.
for example:

example3:
{
    "op": ">",
    "lhs": "publishDate",
    "rhs": "2009-01-01",
    "type": "Date"
}
=> all entities whose publishDate is after 2009-01-01

2. RANGE format:
This is used with Ternary operators, where:
op: operator type ( between )
lhs: left hand side, should be the entity field name.
range1: the start of the range
range2: the end of the range

example4:
{
    "op": "between",
    "lhs": "deathDate",
    "range1": "1999-06-01",
    "range2": "2003-12-01",
    "type": "Date"
}
=> all entities whose deathDate is in the range inclusive [1999-06-01 , 2003-12-01]

example5:
{
    "op": "between",
    "lhs": "age",
    "range1": 18,
    "range2": 28
}
=> all entities whose age is in the range inclusive [18, 28]

example6:
{
    "op": "&&",
    "lhs": {
        "op": "between",
        "lhs": "publishDate",
        "range1": "1999-06-01",
        "range2": "2003-12-01",
        "type": "Date"
    },
    "rhs": {
        "op": "||",
        "lhs": {
            "op": "like",
            "lhs": "name",
            "rhs": "% of %"
        },
        "rhs": {
            "op": ">",
            "lhs": "noPages",
            "rhs": 800
        }
    }
}
=> all entities that:
        has been published in the range inclusive [1999-06-01 , 2003-12-01]
        and 
            either 
                   its name is similar to the token " of " 
                or its number of pages is more than 800

example7
{
    "op": "=",
    "lhs": "books.title",
    "rhs": "Artificial Intelligence"
}

=> All the authors who authored the book of title: 'Artificial Intelligence'
Notice that the Author has a relation Many To Many to Book entity 
and there is a list inside the Author called books
This will allow you to query for nested entities inside the root entity
The nesting level is infinite as long as there is a relation.

JSON schema validation (todo) Handle Invalid Input: wrong key

Update Where

Transitive Dependency

Post Hooks Missing Hooks

Support WildCard

CrudService should be protected