Siminov Android ORM (Object-relational Mapping)

• Siminov Andiorm 0.9-Beta - JAR
• Siminov Andiorm 0.9-Beta - Source

Introduction

Siminov Andiorm is an object-relational mapping (ORM) library for the Android Java language, providing a framework for mapping an object-oriented domain model to a traditional relational database. Siminov solves object-relational impedance mismatch problems by replacing direct persistence-related database accesses with high-level object handling functions.

Siminov is a free software that is distributed under the Apache License, Version 2.0 (the "License").

Siminov Andiorm primary feature is mapping from Android Java classes to database tables (and from Java data types to SQLite data types). Siminov also provides data query and retrieval facilities. It also generates the SQLite calls and attempts to relieve the developer from manual result set handling and object conversion and keep the application portable to all supported SQLite databases with little performance overhead.

All the Features You Need

• Easy Configuration

  • Application Descriptor: Application Descriptor is the one that connects application to Siminov Framework. It provides basic information about the application, which defines the behavior of application.

    <!-- Design Of ApplicationDescriptor.si.xml -->
    
    <siminov>
        
    	<!-- General Application Description Properties -->	
    		<!-- Mandatory Field -->
    	<property name="name">application_name</property>	
    	
    		<!-- Optional Field -->
    	<property name="description">application_description</property>
    	
    		<!-- Mandatory Field (Default is 0.0) -->
    	<property name="version">application_version</property>
    
    
    
    	<!-- Siminov Framework Performance Properties -->	
    		<!-- Optional Field (Default is true)-->
    	<property name="load_initially">true/false</property>
    
    
    
    	<!-- Database Descriptors Used By Application (zero-to-many) -->	
    		<!-- Optional Field's -->
    	<database-descriptors>
    		<database-descriptor>full_path_of_database_descriptor_file
    		</database-descriptor>
    	</database-descriptors>
    	
    
    
    	<!-- Event Handlers Implemented By Application (zero-to-many) -->	
    		<!-- Optional Field's -->
    	<event-handlers>
    		<event-handler>full_class_path_of_event_handler_
    		(ICoreHandler/IDatabaseHandler)</event-handler>
    	</event-handlers>
    
    </siminov>

  • Database Descriptor: Database Descriptor is the one which defines the schema of database.

    <!-- Design Of DatabaseDescriptor.si.xml -->
    
    <database-descriptor>
    
            <!-- General Database Descriptor Properties -->    
    	        <!-- Mandatory Field -->
    	<property name="database_name">name_of_database_file</property>
    
    	        <!-- Optional Field (Default is sqlite)-->
    	<property name="type">type_of_database</property>
    
    		<!-- Optional Field -->
    	<property name="description">database_description</property>
    
    		<!-- Optional Field (Default is false) -->
    	<property name="is_locking_required">true/false</property>
    	
    		<!-- Optional Field (Default is false) -->
    	<property name="external_storage">true/false</property>
    
    				
    	<!-- Database Mapping Descriptor Paths Needed Under 
    	This Database Descriptor -->	
    	        <!-- Optional Field -->
    	<database-mappings>
    		<database-mapping 
    		path="full_path_of_database_mapping_descriptor_file" />
    	</database-mappings>
    
    
    	<!-- Libraries Needed Under This Database Descriptor -->	
    	        <!-- Optional Field -->
    	<libraries>
    		<library>full_path_of_library_descriptor_file</library>
    	</libraries>
    	
    </database-descriptor>

  • Library Descriptor: Library Descriptor is the one that defines the properties of library.

    <!-- Design Of LibraryDescriptor.si.xml -->
    
    <library>
    
            <!-- General Library Properties -->
        		<!-- Mandatory Field -->
    	<property name="name">name_of_library</property>
    	
    		<!-- Optional Field -->
    	<property name="description">description_of_library</property>
    
    	
    	
    	<!-- Database Mapping Descriptor Paths Needed Under 
    	This Library Descriptor -->	
    		<!-- Optional Field -->
    	<database-mappings>
    		<database-mapping 
    		path="full_path_of_database_mapping_descriptor_file" />
    	</database-mappings>
    	 
    </library>

  • Database Mapping Descriptor: Database Mapping Descriptor is one which does ORM, it maps POJO class to database table.

    <!-- Design Of DatabaseMappingDescriptor.si.xml -->
    
    <database-mapping>
    
        <!-- General Properties Of Table And Class -->
        
    	    <!-- TABLE_NAME: Mandatory Field -->
    	    <!-- CLASS_NAME: Mandatory Field -->
    	<table table_name="name_of_table" 
    	class_name="mapped_pojo_class_name">
    		
    	    <!-- Column Properties Required Under This Table -->
    	    
    		<!-- Optional Field -->
    		
    			<!-- VARIABLE_NAME: Mandatory Field -->
    			<!-- COLUMN_NAME: Mandatory Field -->
    		<column variable_name="class_variable_name" 
    		column_name="column_name_of_table">
    		    
    		<!-- Mandatory Field -->
    		<property name="type">
    		int/java.lang.Integer/long/java.lang.Long/float/java.lang.Float/
    		boolean/java.lang.Boolean/char/java.lang.Character/java.lang.String/
    		void/java.lang.Void/short/java.lang.Short</property>
    			
    			<!-- Optional Field (Default is false) -->
    		<property name="primary_key">true/false</property>
    			
    			<!-- Optional Field (Default is false) -->
    		<property name="not_null">true/false</property>
    			
    			<!-- Optional Field (Default is false) -->
    		<property name="unique">true/false</property>
    			
    			<!-- Optional Field -->
    		<property name="check">condition_to_be_checked 
    		(Eg: variable_name 'condition' value; variable_name > 0)</property>
    			
    			<!-- Optional Field -->
    		<property name="default">
    		default_value_of_column (Eg: 0.1)</property>
    		
    		</column>			
    		
    		<!-- Index Properties -->
    				
    		<!-- Optional Field -->
    			<!-- NAME: Mandatory Field -->
    			<!-- UNIQUE: Optional Field (Default is false) -->
    		<index name="name_of_index" unique="true/false">
    			<column>column_name_needs_to_add</column>
    		</index>		
    		
    		<!-- Map Relationship Properties -->
    				
    		<!-- Optional Field -->	
    		<relationships>
    		    
    			    <!-- REFER: Mandatory Field -->
    			    <!-- REFER_TO: Mandatory Field -->
    			<one-to-one refer="class_variable_name" 
    			refer_to="map_to_pojo_class_name" on_update="
    			cascade/restrict/no_action/set_null/set_default" 
    			on_delete="cascade/restrict/no_action/set_null/set_default">
    					
    					<!-- Optional Field (Default is false) -->
    				<property name="load">true/false</property>
    			</one-to-one>		
    			
    			    <!-- REFER: Mandatory Field -->
    			    <!-- REFER_TO: Mandatory Field -->
    			<one-to-many refer="class_variable_name" 
    			refer_to="map_to_pojo_class_name" 
    			on_update="cascade/restrict/no_action/set_null/set_default" 
    			on_delete="cascade/restrict/no_action/set_null/set_default">
    					
    					<!-- Optional Field (Default is false) -->
    				<property name="load">true/false</property>
    			</one-to-many>		
    
    		            <!-- REFER: Mandatory Field -->
    			    <!-- REFER_TO: Mandatory Field -->
    			<many-to-one refer="class_variable_name" 
    			refer_to="map_to_pojo_class_name" 
    			on_update="cascade/restrict/no_action/set_null/set_default" 
    			on_delete="cascade/restrict/no_action/set_null/set_default">
    					
    					<!-- Optional Field (Default is false) -->
    				<property name="load">true/false</property>
    			</many-to-one>		
    
    			    <!-- REFER: Mandatory Field -->
    			    <!-- REFER_TO: Mandatory Field -->
    			<many-to-many refer="class_variable_name" 
    			refer_to="map_to_pojo_class_name" 
    			on_update="cascade/restrict/no_action/set_null/set_default" 
    			on_delete="cascade/restrict/no_action/set_null/set_default">
    					
    					<!-- Optional Field (Default is false) -->
    				<property name="load">true/false</property>
    			</many-to-many>		
    									
    		</relationships>
    
    	</table>
    
    </database-mapping>

• Application Deployment

  All resources required by application are created and managed by Siminov Framework. (E.g.: Creating Application Database, Deploying Application, Managing Relationships, Generating Database Queries).

• Multiple Schemas Supported

  Siminov Framework provides an easy way to support multiple schemas if required by application. Using descriptors developer can define properties of database.

• Events Notifier

  Siminov provides event notification by which application gets notification if there is any event triggered by the framework.
  • Siminov Events: ISiminov is a event handler which automatically gets triggered when any action happen in framework. The application has to provide implementation for ISiminov event notifier and register them with siminov.

    public interface ISiminovEvents {
    	public void firstTimeSiminovInitialized();
    	public void siminovInitialized();
    	public void siminovStopped();
    }

  • Database Events: IDatabase is a event handler which automatically gets triggered when action happens with database. Application has to provide implementation for IDatabase event notifier and register them with siminov.

    public interface IDatabase {
    	public void openOrCreate
    	(final DatabaseDescriptor databaseDescriptor) throws DatabaseException;
    	public void close
    	(final DatabaseDescriptor databaseDescriptor) throws DatabaseException;
    	public void executeQuery
    	(final DatabaseDescriptor databaseDescriptor, 
    	final DatabaseMappingDescriptor databaseMappingDescriptor, 
    	final String query) throws DatabaseException;
    	public void executeBindQuery(final DatabaseDescriptor databaseDescriptor, 
    	final DatabaseMappingDescriptor databaseMappingDescriptor, 
    	final String query, final Iterator columnValues) throws DatabaseException;
    	public Iterator executeFetchQuery(final DatabaseDescriptor databaseDescriptor, 
    	final DatabaseMappingDescriptor databaseMappingDescriptor, final String query) 
    	throws DatabaseException;
    	public void executeMethod(final String methodName, final Object parameters) 
    	throws DatabaseException;
    }

• Database APIs

  • Create and Drop Database

    public class Database {
    	public static IDatabase createDatabase(DatabaseDesriptor) 
    		throws DatabaseException;
    }

  • Create and Drop Table
  • Create and Drop Index
  • Select

    	public ISelect select() throws DatabaseException;

  • Save

    	public final void save() throws DatabaseException;

    Example

    	Liquor beer = new Liquor();
    	beer.setLiquorType(Liquor.LIQUOR_TYPE_BEER);
    	beer.setDescription(applicationContext.getString(R.string.beer_description));
    	beer.setHistory(applicationContext.getString(R.string.beer_history));
    	beer.setLink(applicationContext.getString(R.string.beer_link));
    	beer.setAlcholContent(applicationContext.getString(R.string.beer_alchol_content));
    
    	try {
    		beer.save();
    	} catch(DatabaseException de) {
    		//Log it.
    	}

  • Update

    public final void update() throws DatabaseException;

    Example

    	Liquor beer = new Liquor();
    	beer.setLiquorType(Liquor.LIQUOR_TYPE_BEER);
    	beer.setDescription(applicationContext.getString(R.string.beer_description));
    	beer.setHistory(applicationContext.getString(R.string.beer_history));
    	beer.setLink(applicationContext.getString(R.string.beer_link));
    	beer.setAlcholContent(applicationContext.getString(R.string.beer_alchol_content));
     
    	try {
    		beer.update();
    	} catch(DatabaseException de) {
    		//Log it.
    	}

  • Save Or Update

    public final void saveOrUpdate() throws DatabaseException;

    Example

    Liquor beer = new Liquor();
    	beer.setLiquorType(Liquor.LIQUOR_TYPE_BEER);
    	beer.setDescription(applicationContext.getString(R.string.beer_description));
    	beer.setHistory(applicationContext.getString(R.string.beer_history));
    	beer.setLink(applicationContext.getString(R.string.beer_link));
    	beer.setAlcholContent(applicationContext.getString(R.string.beer_alchol_content));
    
    	try {
    		beer.saveOrUpdate();
    	} catch(DatabaseException de) {
    		//Log it.
    	}

  • Delete

    public final void delete() throws DatabaseException { }

    Example

    	Liquor beer = new Liquor();
    	beer.setLiquorType(Liquor.LIQUOR_TYPE_BEER);
    	beer.setDescription(applicationContext.getString(R.string.beer_description));
    	beer.setHistory(applicationContext.getString(R.string.beer_history));
    	beer.setLink(applicationContext.getString(R.string.beer_link));
    	beer.setAlcholContent(applicationContext.getString(R.string.beer_alchol_content));
    
    	try {
    		beer.delete();
    	} catch(DatabaseException de) {
    		//Log it.
    	}

• Aggregation APIs

  • Count

    public ICount count() throws DatabaseException;

  • Average

    public IAverage avg() throws DatabaseException;

  • Sum

    public ISum sum() throws DatabaseException;

  • Total

    public ITotal total() throws DatabaseException;	

  • Minimum

    public IMin min() throws DatabaseException;

  • Maximum

    public IMax max() throws DatabaseException;

  • Group Concat

    public IGroupConcat groupConcat() throws DatabaseException;	

• Database Transaction APIs

  • Begin Transaction

    public static final void beginTransaction
    (final DatabaseDescriptor databaseDescriptor) throws DatabaseException;

  • Commit Transaction

    public static final void commitTransaction
    (final DatabaseDescriptor databaseDescriptor) throws DatabaseException;	

  • End Transaction

    public static final void endTransaction
    (final DatabaseDescriptor databaseDescriptor);

• Database Encryption (SQLCipher)

  Data Security plays an important role when we talk about database. It protect your database from destructive forces and the unwanted actions of unauthorized users.

  Siminov provides implementation for SQLCipher to protect application database from any unauthorized users.

• Handling Libraries Based ORM

  An Android library project is a development project that holds shared Android source code and resources. Other Android application projects can reference the library project and, at build time, include its compiled sources in their .apk files.

  Siminov provides a mechanism to configure ORM for your library projects.

License

[SIMINOV FRAMEWORK] Copyright [2013] [Siminov Software Solution|support@siminov.com] 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.

Conclusion

If you are looking to bridge the object-relational impedance mismatch and increase your productivity and data access performance, you should consider the Siminov Andiorm. It offers all features which you need in an ORM like Easy Configuration, Application Deployment, Multiple Schema's Supported, Events Notifier, Database APIs, Aggregation APIs, Database Transaction APIs, Database Encryption (SQLCipher), Handling Libraries Based ORM.

• Product Website
• Github Repository
• Wiki
• Developers Guide
• Getting Started Guide
• Java Docs