Basics_en
After downloading the jar file you have to add it to the classpath. Then you can use it to create, run and execute commands on the database.
Sofof follows the same life cycle as any other database (Look at the figure).
The database is presented by the class Server in the package org.sofof which provides database configuring service. Using this class you can create a new database by creating a new instance by passing the database file to its constructor and calling the method public boolean createDatabase(). If the file exists the method will return false. Else it will return true and create a new database. This method will throw an IOException when there is a problem while creating database files.
import java.io.File;
import org.sofof.SofofException;
import org.sofof.Server;
public class CreateDatabase{
public static void main(String[] args){
try{
new Server(new File("C:/Users/LENOVO PC/Desktop/sofofDB")).createDatabase();
}catch(SofofException ex){
System.err.println(ex.getMessage());
}
}
}When you try to open the folder sofofDB you will find this:
The binds file contains configurations and information about the database.
This Server class is the real engine for the database. It's a Thread and it has many constructors. One of them has three parameters the database folder and the port to listen to on the computer and the connection type (SSL or not). You can start up the server by the method startUp() which will throw a SofofException when there is a problem in the IO. This is a simple example of how to start up a server on a certain database.
import java.io.File;
import org.sofof.Server;
import org.sofof.SofofException;
public class ServerStartUp{
public static void main(String[] args) throws SofofException{
Server server = new Server(new File("C:/Users/LENOVO PC/Desktop/sofofDB"), 6969, false);
server.startUp();
}
}When you try to start up the server it will read the database configurations from the database folder. Then it will listen to the passed port which is in this cause 6969. As will the Server is a Thread it's configured to be a daemon thread and it will shut down automatically when all remaining threads aren't daemon. To prevent this you can use the method setDaemon() and pass the parameter false to it so it won't close until you shut down the server using the method shutDown() else your program won't stop and the Server will work in the background.
Sofof has an authentication system that is prepared each time you want to start the server. This system composed of users which presented by the class User from the package org.sofof.permission. It defines the user by a username and a password. You can assign the username and the password by creating a new User instance with the only constructor in the class. After that, you have to add that instance to the user's list in the server getUsers().add(). You can specify the permissions to the user by implementing the interface SofofSecurityManager. Then you should assign it as a SecurityManager and the server will ask it before answering any command. It has two methods checkExecutable(User, Executable) and checkQuery(User, Query) that you will implement to write your own conditions on executing the commands and throwing SecurityException when you want to prevent the user from executing or querying. This example will explain how to add a user to the server.
import org.sofof.Server;
import org.sofof.SofofException;
import org.sofof.permission.User;
import java.io.File;
public class AdminUser{
public static void main(String[] args) throws SofofException{
Server server = new Server(new File("C:/Users/LENOVO PC/Desktop/sofofDB"), 6969);
User rami = new User("rami", "manaf");
server.getUsers().add(rami);
server.startUp();
}
}After you have prepared the server, add the users and start the server there is a final step to use the database. This step is starting a Session which will open a connection with the server so you can send the commands for execution. You can start a session using the static method startSession(String url, User user, boolean ssl) in the SessionManager. This method has three parameters. The first one is the connection url. This string has a structure of three sections separated from each other with (:) symbol as follows serializer:host:port. The serializer will be described later but until that use "sofof". The host is the host that the server is working on (it could be an IP number or a domain name e.g: localhost, site.com, 127.32.44.1) and port is the port that you have chosen the server to listen to. The second parameter is the User that you want to log in with his name and the third boolean parameter is the type of the connection (SSL or not). If the user wasn't registered in the server or there is no server listening to that host and port the method will throw an exception. Finally, if you finished using the session object you have to close it through close() method.
import org.sofof.Server;
import org.sofof.SofofException;
import org.sofof.SessionManager;
import org.sofof.Session;
import org.sofof.permission.User;
import java.io.File;
public class Login{
public static void main(String[] args) thorws SofofException{
Server server = new Server(new File("C:/Users/LENOVO PC/Desktop/sofofDB"), 6969, false);
User rami = new User("rami", "manaf");
server.getUsers().add(rami);
server.startUp();
Session session = SessionManager.startSession("sofof:localhost:6969", new User("rami", "manaf"), false);
session.close();
}
}There is two types of commands Executable and Query. The Executable goal is to do processes that change the data in the database and the Query goal is to read the stored data in the database. You can execute the Executable through the method execute(Executable) on the Session object and the method should return the int number of effected objects. You can query about objects through passing the Query to the query(Query) method and it should return a list of the selected objects. the both Query and Executable implementations are presented under the package org.sofof.command.
Sofof depends on binding names with storing the data. The binding name is a name that you can link objects to it from many classes e.g: binding Student objects to a "students" binding name. There is no linkage between different binding names.
The goal of using the executable expression is doing processes on the objects. You can call methods and fields and its syntax is similar to Java. This is the executable expression rules:
- Always start with a # symbol
- You can write the name of the fields and methods directly.
- If you want to return the value of the object without any effect don't write anything after the # symbol.
- You have to write two parentheses when you want to call a method after its name whether the method has parameters or not.
- If you want to call a method or get a value of a field on the returned value from calling another method or a field you can just write a dot "." then write the method or field name like Java.
- When calling a method you have to write the method parameters inside the parentheses just like in Java. After that you have to write a letter that specifies the type of the parameter in the method definition e.g: you can pass String to an Object parameterized method. If you didn't write anyone the default types int and float. This table will show the letters and their meanings.
- To access an array element you can use the brackets just like in Java.
| Class | letter | Note |
|---|---|---|
| String | S | Surround with double-quote |
| Character | C | Surround with quote |
| Integer | I | |
| Float | F | have one decimal point |
| Long | L | |
| Short | H | |
| Double | D | |
| Byte | B | |
| Object | O | You can use it for int, float, char, String only |
If you want to pass the data as a primitive data you can write the previous letters in the small form e.g: for int type you have to write i. Some commands let you use the executable expression. Each one will execute that expression to achieve certain results that you want e.g: Select command enables you to use an executable expression by passing it as a second parameter in the constructor then execute that expression on the selected objects and will return the result from that execution. To obvious that you can imagine that you stored School objects and you want to select all the principals then you should write the following code:
List directors = sess.query(new Select(School.class, "#getDirector()"));You can use the Server without opening any port in the device to execute commands on a database. You can achieve this by passing -1 as a port number or not passing any value to it. This service doesn't provide the authentication service. After that, you can start up the server and call the methods execute and query to execute commands, but if you want to use them for a non-local database they will throw an exception.
Serialization is the process of converting objects to bytes and deserialization does the opposite. Sofof database separates the mission of serialization and deserialization of objects from Session and Server and represents it using the org.sofof.serializer.Serializer interface which has two methods for serializing and deserializing. The serializer also has a unique name. Sofof has a default serializer SofofSerializer and it's unique name is sofof. The serializer is used in the process of transferring objects between the session and the server. You can set the serializer you want to be used by the server using the setSerializer(Serializer serializer) method on the Server object. You can use a serializer with a session by registering it first to the SessionManager using the registerSerializer(Serializer serializer) method. Then you can start a session that uses this serializer by writing its unique name in the first section of the url instead of writing sofof. Currently Sofof has three serializers:
- SofofSerializer: This serializer unique name is sofof. It saves the class fields names and values so you can add and remove fields freely but you have to offer a default constructor with no arguments. You don't have to implement Serializable interface but for classes that does Sofof serializer serialize them using java serialization API.
- JavaSerializer: This serializer unique name is java. It uses the java serialization API to serialize objects. All classes that will be serialized by this class should implement Serializable interface and long serialVersionUID field. Any change in the class fields can cause a problem if you didn't define a serialization method for the class. It's very recommended to use Sofof serializer instead of this.
- JsonSerializer: This serializer unique name is json. It can serialize simple objects to json. You should pay attention that this serializer doesn't support serializing complex classes. It simply stores String ,primitive, array and collection as json no more than that. Currently doesn't support multidimensional arrays and classes should have a default constructor with no arguments.