Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/roll-w/light

A simple and lightweight relational database development module for Java.
https://github.com/roll-w/light

java java-8 java-annotations java-library jdbc mysql sql sqlite sqlite3

Last synced: about 1 month ago
JSON representation

A simple and lightweight relational database development module for Java.

Awesome Lists containing this project

README 

        
# Light



[![Maven Central][mcBadge]][mcLink] [![License][liBadge]][liLink]



A simple and lightweight relational database development module.



## Required



JDK 1.8 or higher.



## Getting Started



To add dependencies on Light using Maven, use the following:



```xml



    

    

        space.lingu.light

        light-compiler

        0.4.6

        provided

    



    

    

        space.lingu.light

        light-core

        0.4.6

    



```



Or using Gradle:



```groovy

dependencies {

    compileOnly("space.lingu.light:light-compiler:0.4.6")



    implementation("space.lingu.light:light-core:0.4.6")

}

```



After adding dependencies, you can now use Light to help you build your database.



## Usage Example



Here is a simple example of using Light to build a database with tables.



### Define a table



Here defines a `User` table.

Each instance of `User` represents a column in the data table.



```java



@DataTable

public class User {

    @PrimaryKey

    @DataColumn

    private long uid;



    @DataColumn(name = "first_name")

    private String firstName;



    @DataColumn(name = "last_name")

    private String lastName;



    // ... setters and getters

}

```



Light uses the class name as the table name unless you specify the table name manually.



In this case, the table name is _User_.



Similar rules apply to column names. Light uses the field name as the column name

unless you specify the column name manually.



### Create a Data Access Object (DAO)



To access the data in the database, you need to create a DAO.



Here is a simple example for the `User` table.



```java



@Dao

public interface UserDao {

    @Insert

    void insert(User... users);



    @Update

    void update(User... users);



    @Delete

    void delete(User user);



    @Query("SELECT * FROM User")

    List get();



    @Query("SELECT * FROM User WHERE uid IN ({ids})")

    List getByIds(int[] ids);

}

```



The `@Dao` annotation indicates that this is a DAO,

and the DAO class needs to be an interface or abstract class.



By use the `{}` to specify the SQL parameter,

Light will automatically replace the parameter with the corresponding value.



What's more, you can write a simple expression in the `{}`. Such as:



```java



@Query("SELECT * FROM User WHERE first_name = {user.getFirstName()} AND last_name = {user.getLastName()}")

List getByName(User user);



```



> Currently, Light only supports field access and parameterless method calls in the expression.



### Create a database



After completing the above work, you also need to define a database class

to get the DAO instance.



Here is an example of a database class, it needs to be an abstract class

and extends `LightDatabase`.



```java



@Database(name = "example", version = 1, tables = {User.class})

public abstract class ExampleDatabase extends LightDatabase {

    public abstract UserDao getUserDao();

}



```



When connecting to the database, Light will try to create the database.

But if the database is already specified in the jdbc URL,

this step will be skipped.



After connecting to the database, Light will try to create tables 

that are not yet created. 



### Set up connection URL



When connecting to the database, you need to specify the connection URL

and also the jdbc driver class name in the `light.properties` file

(or you can specify the path in the `@Database` annotation) in the

classpath.



Here we use the MySQL database as an example.



```properties

light.data.url=jdbc:mysql://localhost:3306/

light.data.jdbcName=com.mysql.cj.jdbc.Driver

# Set your username and password if needed

light.data.username=root

light.data.password=123456

```



Or you can replace `data` with your database name, in this case is `example`.



### Last step, get ready to go!



To get the DAO instance, you need to build the database class instance.



Define in somewhere of your code:



```java

public static ExampleDatabase buildDatabase() {

    return Light.databaseBuilder(ExampleDatabase.class, MySQLDialectProvider.class)

            // This connection pool implementation is low performance and is used only as a test.

            // Can be replaced with Hikari Connection Pool, etc.

            .setConnectionPool(DisposableConnectionPool.class)

            // Optional, use light-core-logger-slf4j/LightSlf4jLogger as logger

            .setLogger(LightSlf4jLogger.createLogger(ExampleDatabase.class))

            .build();

}

```



Note: `DialectProvider` and `ConnectionPool` are must be specified.



We suggest that you use a singleton pattern to save the database instance.



## License



```text

   Copyright (C) 2022 Lingu Light Project



   Licensed under the Apache License, Version 2.0 (the "License");

   you may not use this file except in compliance with the License.

   You may obtain a copy of the License at



       http://www.apache.org/licenses/LICENSE-2.0



   Unless required by applicable law or agreed to in writing, software

   distributed under the License is distributed on an "AS IS" BASIS,

   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

   See the License for the specific language governing permissions and

   limitations under the License.

```



[liBadge]: https://img.shields.io/github/license/Roll-W/light?color=569cd6&style=flat-square



[liLink]: https://github.com/Roll-W/light/blob/master/LICENSE



[mcBadge]: https://img.shields.io/maven-central/v/space.lingu.light/light-parent?style=flat-square



[mcLink]: https://search.maven.org/search?q=g:space.lingu.light