Bibernate Framework Documentation

Getting Started

If you're new to the Bibernate, consider initiating your experience with a Bibernate Playground Application with a variety of examples of how to use it. The Bibernate offers a swift and opinionated method to develop a Bibernate-based application ready for play.

Bibernate Framework Overview

The Bibernate simplifies the development of Java enterprise applications and efficient ORM (Object-Relational Mapping) framework designed to simplify database interaction in Java applications by providing comprehensive support for leveraging the Java language within an enterprise setting. Bibernate 1.0 development requires Java 17.

Prerequisites

Before getting started with the Bibernate, ensure you have the following prerequisites installed:

• Java 17
• Your preferred Java IDE such as IntelliJ IDEA
• Docker
• A compatible relational database management system PostgreSQL

Installation

• Open your Maven Project:

Open the Maven project where you want to add the Bibernate framework dependencies.

• Edit pom.xml:

Locate the pom.xml file in your project.

• Add Repository Configuration:

Inside the section of your pom.xml, add the following repository configuration if you want to try the latest Snapshot version of Bibernate project:

  <repositories>
    <repository>
      <releases>
        <enabled>false</enabled>
        <updatePolicy>always</updatePolicy>
        <checksumPolicy>warn</checksumPolicy>
      </releases>
      <snapshots>
        <enabled>true</enabled>
        <updatePolicy>never</updatePolicy>
        <checksumPolicy>fail</checksumPolicy>
      </snapshots>
      <name>Nexus Snapshots</name>
      <id>snapshots-repo</id>
      <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
      <layout>default</layout>
    </repository>
  </repositories>

This configuration informs Maven about the repository location where it can find the Bibernate framework artifacts.

• Include Dependency:

Within the section of your pom.xml, add the Bibernate framework dependency (You will have core & annotation-processor):

    <dependency>
      <groupId>io.github.blyznytsiaorg.bibernate</groupId>
      <artifactId>core</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>

Design Philosophy

The Bibernate embodies educational principles in its design, empowering users to master reflection and architectural design. As a ORM framework, the Bibernate serves as a cornerstone for understanding and implementing persistence in web applications. Its robust features facilitate seamless mapping of Java objects to database tables, simplifying data access and fostering efficient development practices for teams.

Key Features

Bibernate Core

The Bibernate can be described as a library that simplifies the issue of mapping Java classes to relational database tables.

The Bibernate takes the pain out of persistence by freeing the developer from the burden of manually writing tedious, repetitive, and error-prone code to flatten object graphs into database tables and reconstruct object graphs from flat SQL query result sets. Moreover, the Bibernate significantly simplifies performance tuning by allowing developers to focus on writing basic persistence logic first, with the ability to optimize performance later.

Bibernate and API

The Bibernate served as the inspiration behind the Java (now Jakarta) Persistence API, or JPA. While JPA is well-suited for production environments, for educational purposes, we have developed our own simplified version of the Persistence API.

The Bibernate API can be described in terms of three basic elements:

• The EntityManagerFactory is typically created during application startup based on configuration settings and entity mappings.
• The BibernateSessionFactory is responsible for creating and managing BibernateSession instances.
• The BibernateSession is a fundamental component of Bibernate, analogous to the Session interface in Hibernate.

Documentation

• There are two types of documentation: Markdown (see below) and JavaDoc (core), JavaDoc (annotation processor)

Features:

• Object-Relational Mapping (ORM): Simplifies the mapping of Java objects to relational database tables and vice versa, eliminating the need for manual SQL queries.
• Automatic Persistence: Automatically manages the lifecycle of persistent objects, tracking changes and synchronizing them with the database.
• Bibernate Query Language(BQL): Provides a powerful query language similar to SQL but operates on Java objects, enabling database queries using object-oriented concepts.
• Caching Mechanisms: Supports first-level and second-level caching to improve performance by reducing database queries and minimizing latency.
• Transaction Management: Offers built-in support for managing database transactions, ensuring data integrity and consistency across multiple operations.
• Lazy Loading: Delays the loading of associated objects until they are explicitly accessed, improving performance by loading only what is necessary.
• Criteria API: Allows developers to build dynamic queries programmatically and fluent interface, enhancing query flexibility
• Native SQL Queries:: Allows execution of native SQL queries when needed, providing flexibility and compatibility with existing database schemas.
• Schema Generation: Offers tools for generating database schemas based on entity mappings, simplifying database setup.
• Extensibility: Provides a flexible architecture that allows developers to extend and customize Bibernate functionality to meet specific application requirements.
• Bibernate Data Repository: Bibernate Data Repository is a powerful feature provided by the Bring Framework that simplifies the process of interacting with databases, particularly in the context of Bibernate persistent API.
• Versioning: Supports versioning of entity data and implementing optimistic concurrency control.
• Flyway Migration Support: Integrates seamlessly with Flyway migration tool, enabling database schema management and version control through declarative SQL migration scripts. This ensures consistency and reliability in database schema evolution across different environments.
• Batch Processing: Facilitates batch processing of database operations, improving performance by minimizing round-trips to the database.
• Configuration Management: Offers flexible configuration options, allowing for default settings or external settings specified in a configFile or passed as parameters.

Annotations:

• @Entity
• @Table
• @Index
• @Id
• @GeneratedValue
• @SequenceGenerator
• @Column
• @JoinColumn
• @JoinTable
• @ForeignKey
• @OneToOne
• @OneToMany
• @ManyToOne
• @ManyToMany
• @CreationTimestamp
• @UpdateTimestamp
• @Version
• @Param
• @Query
• @DynamicUpdate
• @Immutable
• @IgnoreEntity

Exceptions:

• BibernateDataSourceException
• BibernateGeneralException
• BibernateSessionClosedException
• BibernateValidationException
• ClassLimitationCreationException
• CollectionIsEmptyException
• ConnectionPoolException
• EntitiesNotFoundException
• EntityNotFoundException
• EntityStateWasChangeException
• FailedToMatchPropertyException
• ImmutableEntityException
• MappingException
• MissingAnnotationException
• MissingRequiredParametersInMethod
• NonUniqueResultException
• NotFoundImplementationForCustomRepository
• RepositoryInvocationException
• UnsupportedActionTypeException
• UnsupportedDataTypeException
• UnsupportedReturnTypeException

Additional items:

• Annotation Processing: Ensure entity validation for proper usage during compile time.
• Runtime Entity Validation: During the initialization of the application, we'll log warnings or exceptions and offer guidance on best practices for code improvement.
• Reflection Optimization: We gather all the details during startup and store them for later use because reflection is slow.

Feedback and Contributions

If you suspect an issue within the Bibernate ORM Framework or wish to propose a new feature, kindly utilize GitHub Issues for reporting problems or submitting feature suggestions If you have a solution in mind or a suggested fix, you can submit a pull request on Github. In addition, please read and configure you idea to follow our Setup Code Style Guidelines