Released 6.0.0

Author: CollinAlpert

README.md

@@ -6,7 +6,7 @@
 
     <groupId>com.github.collinalpert</groupId>
     <artifactId>java2db</artifactId>
-    <version>5.6.0</version>
+    <version>6.0.0</version>
     <packaging>jar</packaging>
 
     <name>Java2DB</name>
@@ -62,7 +62,7 @@
         <dependency>
             <groupId>com.github.collinalpert</groupId>
             <artifactId>lambda2sql</artifactId>
-            <version>2.3.0</version>
+            <version>2.4.0</version>
         </dependency>
 
         <dependency>
@@ -111,7 +111,10 @@
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>3.2.0</version>
                 <configuration>
-                    <additionalOptions>-html5</additionalOptions>
+                    <additionalOptions>
+                        <additionalOption>-html5</additionalOption>
+                        <additionalOption>-Xdoclint:none</additionalOption>
+                    </additionalOptions>
                 </configuration>
                 <executions>
                     <execution>

pom.xml

@@ -23,6 +23,9 @@
 
 	JoinTypes joinType() default JoinTypes.LEFT;
 
+	/**
+	 * An enum for specifying the type of join to use when leveraging the automatic join feature via the {@link ForeignKeyEntity} attribute.
+	 */
 	enum JoinTypes {
 		LEFT("left"),
 		INNER("inner"),

src/main/java/com/github/collinalpert/java2db/annotations/ForeignKeyEntity.java

@@ -6,7 +6,7 @@
 
 /**
  * This annotation is used to indicate that only a specific column of a table is supposed to be joined when executing the query.
- * It has to be used in conjunction with the {@link ForeignKeyEntity} attribute.
+ * It must be used in conjunction with the {@link ForeignKeyEntity} attribute.
  *
  * @author Collin Alpert
  */

src/main/java/com/github/collinalpert/java2db/annotations/ForeignKeyPath.java

@@ -7,5 +7,5 @@
  * @author Collin Alpert
  */
 public interface IdentifiableEnum {
-	long getId();
+	int getId();
 }

src/main/java/com/github/collinalpert/java2db/contracts/IdentifiableEnum.java

@@ -0,0 +1,79 @@
+package com.github.collinalpert.java2db.database;
+
+/**
+ * A container for database access. Contains all necessary information for this library to access a database.
+ *
+ * @author Collin Alpert
+ */
+public class ConnectionConfiguration {
+
+	/**
+	 * Specifies the hostname/ip address of the database.
+	 */
+	private final String host;
+
+	/**
+	 * Specifies the name of the database to connect to.
+	 */
+	private final String database;
+
+	/**
+	 * Specifies the username to log in on the database with.
+	 */
+	private final String username;
+
+	/**
+	 * Specifies the password to log in on the database with.
+	 */
+	private final String password;
+
+	/**
+	 * Specifies the port to connect to the database on.
+	 * This property is optional. If not specified, it will be set to 3306, the default port of MySQL.
+	 */
+	private final int port;
+
+	/**
+	 * Specifies the login timeout to the database in seconds. Default is 5 seconds.
+	 */
+	private final int timeout;
+
+	public ConnectionConfiguration(String host, String database, String username, String password) {
+		this(host, database, username, password, 3306, 5);
+	}
+
+	public ConnectionConfiguration(String host, String database, String username, String password, int port, int timeout) {
+		this.host = host;
+		this.database = database;
+		this.username = username;
+		this.password = password;
+		this.port = port;
+		this.timeout = timeout;
+	}
+
+	public String getHost() {
+		return host;
+	}
+
+	public String getDatabase() {
+		return database;
+	}
+
+	public String getUsername() {
+		return username;
+	}
+
+	public String getPassword() {
+		return password;
+	}
+
+	public int getPort() {
+		return port;
+	}
+
+	public int getTimeout() {
+		return timeout;
+	}
+
+
+}

src/main/java/com/github/collinalpert/java2db/database/ConnectionConfiguration.java

@@ -16,41 +16,13 @@
 import static com.github.collinalpert.java2db.utilities.Utilities.supplierHandling;
 
 /**
+ * Wrapper around {@link Connection} which eases use of connecting to a database and running queries.
+ * Also supports running functions and stored procedures.
+ *
  * @author Collin Alpert
  */
 public class DBConnection implements Closeable {
 
-	/**
-	 * Specifies the hostname/ip address of the database.
-	 */
-	public static String HOST;
-
-	/**
-	 * Specifies the name of the database to connect to.
-	 */
-	public static String DATABASE;
-
-	/**
-	 * Specifies the username to log in on the database with.
-	 */
-	public static String USERNAME;
-
-	/**
-	 * Specifies the password to log in on the database with.
-	 */
-	public static String PASSWORD;
-
-	/**
-	 * Specifies the port to connect to the database on.
-	 * This property is optional. If not specified, it will be set to 3306, the default port of MySQL.
-	 */
-	public static int PORT = 3306;
-
-	/**
-	 * Specifies the login timeout to the database in seconds.
-	 */
-	public static int TIMEOUT = 5;
-
 	/**
 	 * Constant which determines if the queries generated by Java2DB will be logged in the console.
 	 */
@@ -59,13 +31,13 @@ public class DBConnection implements Closeable {
 	private Connection underlyingConnection;
 	private boolean isConnectionValid;
 
-	public DBConnection() {
+	public DBConnection(ConnectionConfiguration configuration) {
 		try {
-			var connectionString = String.format("jdbc:mysql://%s:%d/%s?rewriteBatchedStatements=true", HOST, PORT, DATABASE);
+			var connectionString = String.format("jdbc:mysql://%s:%d/%s?rewriteBatchedStatements=true", configuration.getHost(), configuration.getPort(), configuration.getDatabase());
 			Class.forName("com.mysql.cj.jdbc.Driver");
-			System.setProperty("user", USERNAME);
-			System.setProperty("password", PASSWORD);
-			DriverManager.setLoginTimeout(TIMEOUT);
+			System.setProperty("user", configuration.getUsername());
+			System.setProperty("password", configuration.getPassword());
+			DriverManager.setLoginTimeout(configuration.getTimeout());
 			underlyingConnection = DriverManager.getConnection(connectionString, System.getProperties());
 			isConnectionValid = true;
 		} catch (CJCommunicationsException | CommunicationsException e) {
@@ -135,7 +107,7 @@ public ResultSet execute(String query, Object... params) throws SQLException {
 	 * @return the last generated ID. This return value should only be used with INSERT statements.
 	 * @throws SQLException if the query is malformed or cannot be executed.
 	 */
-	public long update(String query) throws SQLException {
+	public int update(String query) throws SQLException {
 		var statement = this.underlyingConnection.createStatement();
 		log(query);
 		statement.executeUpdate(query, Statement.RETURN_GENERATED_KEYS);
@@ -150,7 +122,7 @@ public long update(String query) throws SQLException {
 	 * @return the last generated ID. This return value should only be used with INSERT statements.
 	 * @throws SQLException if the query is malformed or cannot be executed.
 	 */
-	public long update(String query, Object... params) throws SQLException {
+	public int update(String query, Object... params) throws SQLException {
 		var statement = this.underlyingConnection.prepareStatement(query, Statement.RETURN_GENERATED_KEYS);
 		for (int i = 0; i < params.length; i++) {
 			statement.setObject(i + 1, params[i]);
@@ -198,9 +170,9 @@ public void close() {
 	 *
 	 * @param returnType   The Java equivalent of the SQL datatype the function returns.
 	 * @param functionName The name of the function.
-	 * @param arguments    The arguments to be supplied to the function.
+	 * @param arguments    The arguments to be supplied to the function, if any.
 	 * @param <T>          The functions return type.
-	 * @return The value of the function, as a Java datatype.
+	 * @return The return value of the function, as a Java datatype.
 	 * @throws SQLException In case there is an error communicating with the database, i.e. the function does not exist.
 	 */
 	public <T> Optional<T> callFunction(Class<T> returnType, String functionName, Object... arguments) throws SQLException {
@@ -214,22 +186,91 @@ public <T> Optional<T> callFunction(Class<T> returnType, String functionName, Ob
 		}
 	}
 
+	/**
+	 * Calls an SQL function asynchronously.
+	 *
+	 * @param exceptionHandler The exception handler which handles the {@link SQLException} in case something goes wrong.
+	 * @param returnType       The Java type which the result will be mapped into. It needs to have a parameterless constructor available.
+	 * @param functionName     The name of the function to call.
+	 * @param arguments        The arguments to supply to the function, if any.
+	 * @param <T>              The functions return type.
+	 * @return The return value of the function, as a Java datatype.
+	 */
 	public <T> CompletableFuture<Optional<T>> callFunctionAsync(Consumer<SQLException> exceptionHandler, Class<T> returnType, String functionName, Object... arguments) {
 		return CompletableFuture.supplyAsync(supplierHandling(() -> this.callFunction(returnType, functionName, arguments), exceptionHandler));
 	}
 
-	public <T> CompletableFuture<Void> callFunctionAsync(Consumer<SQLException> exceptionHandler, Consumer<? super Optional<T>> callback, Class<T> returnType, String functionName, Object... arguments) {
+	/**
+	 * Calls an SQL function asynchronously. If an exception occurs, it gets printed to the console.
+	 *
+	 * @param returnType   The Java type which the result will be mapped into. It needs to have a parameterless constructor available.
+	 * @param functionName The name of the function to call.
+	 * @param arguments    The arguments to supply to the function, if any.
+	 * @param <T>          The functions return type.
+	 * @return The return value of the function, as a Java datatype.
+	 */
+	public <T> CompletableFuture<Optional<T>> callFunctionAsync(Class<T> returnType, String functionName, Object... arguments) {
+		return CompletableFuture.supplyAsync(supplierHandling(() -> this.callFunction(returnType, functionName, arguments)));
+	}
+
+	/**
+	 * Calls an SQL function asynchronously and applies a {@link Consumer} to the returned value.
+	 *
+	 * @param returnType   The Java type which the result will be mapped into. It needs to have a parameterless constructor available.
+	 * @param callback     A consumer which specifies which action to perform once the function has been called.
+	 * @param functionName The name of the function to call.
+	 * @param arguments    The arguments to supply to the function, if any.
+	 * @param <T>          The functions return type.
+	 * @return The return value of the function, as a Java datatype.
+	 */
+	public <T> CompletableFuture<Void> callFunctionAsync(Class<T> returnType, Consumer<? super Optional<T>> callback, String functionName, Object... arguments) {
+		return CompletableFuture.supplyAsync(supplierHandling(() -> this.callFunction(returnType, functionName, arguments))).thenAcceptAsync(callback);
+	}
+
+	/**
+	 * Calls an SQL function asynchronously and applies a {@link Consumer} to the returned value.
+	 *
+	 * @param exceptionHandler The exception handler which handles the {@link SQLException} in case something goes wrong.
+	 * @param returnType       The Java type which the result will be mapped into. If it is a complex type, it needs to have a parameterless constructor available.
+	 * @param callback         A consumer which specifies which action to perform once the function has been called.
+	 * @param functionName     The name of the function to call.
+	 * @param arguments        The arguments to supply to the function, if any.
+	 * @param <T>              The functions return type.
+	 * @return The return value of the function, as a Java datatype.
+	 */
+	public <T> CompletableFuture<Void> callFunctionAsync(Consumer<SQLException> exceptionHandler, Class<T> returnType, Consumer<? super Optional<T>> callback, String functionName, Object... arguments) {
 		return CompletableFuture.supplyAsync(supplierHandling(() -> this.callFunction(returnType, functionName, arguments), exceptionHandler)).thenAcceptAsync(callback);
 	}
 
+	/**
+	 * Calls a stored procedure and returns a {@link Queryable} to fetch the data in the desired format.
+	 *
+	 * @param returnType          The Java type which the result will be mapped into. If it is a complex type, it needs to have a parameterless constructor available.
+	 * @param storedProcedureName The name of the stored procedure to call.
+	 * @param arguments           The arguments to pass to the stored procedure.
+	 * @param <T>                 The Java type to be returned?
+	 * @return A {@link Queryable} to fetch the data in the desired format.
+	 */
 	public <T> Queryable<T> callStoredProcedure(Class<T> returnType, String storedProcedureName, Object... arguments) {
 		return new StoredProcedureQuery<>(returnType, this, storedProcedureName, arguments);
 	}
 
+	/**
+	 * Calls a stored procedure asynchronously and returns a {@link Queryable} to fetch the data in the desired format.
+	 *
+	 * @param returnType          The Java type which the result will be mapped into. If it is a complex type, it needs to have a parameterless constructor available.
+	 * @param storedProcedureName The name of the stored procedure to call.
+	 * @param arguments           The arguments to pass to the stored procedure.
+	 * @param <T>                 The Java type to be returned?
+	 * @return An {@link AsyncQueryable} to fetch the data in the desired format.
+	 */
 	public <T> AsyncQueryable<T> callStoredProcedureAsync(Class<T> returnType, String storedProcedureName, Object... arguments) {
 		return new AsyncStoredProcedureQuery<>(returnType, this, storedProcedureName, arguments);
 	}
 
+	/**
+	 * @return The {@link Connection} object this class uses to operate on.
+	 */
 	public Connection underlyingConnection() {
 		return this.underlyingConnection;
 	}
@@ -245,11 +286,11 @@ private void log(String text) {
 		}
 	}
 
-	private long updateInternal(Statement statement) throws SQLException {
+	private int updateInternal(Statement statement) throws SQLException {
 		statement.closeOnCompletion();
 		var set = statement.getGeneratedKeys();
 		if (set.next()) {
-			return set.getLong(1);
+			return set.getInt(1);
 		}
 
 		return -1;