# Molecule Database Framework - MDF

## News

**Released Version 1.2.0**

- upgraded versions of several dependiencies inlc. spring-data and querydsl
- improved SaltFactory interface

The SaltFactory interface now has 2 new methods `isSalt(String)` and 
`createSaltCompositions(String)` where the string is a SMILES or molfile. This
makes it possible to pass the structure entered in an UI directly to SaltFactory.
The user only needs to draw the salt as a single composition and it is 
automatically detected and separated into its ions.


### Salt Handling

MDF now has salt handling implemented. To activate, add `chemistry.handleSalts = true`
to the `Application.properties` file. Else the behaviour remains the same as now.
Note that activating this feature has a performance impact especially when
importing large sd-files. 

- Components of salts are stored as an uncharged `ChemicalStructures` (Na, Cl)
- the new entity `SaltComposition` contains the original charged structure (Na+,
  Cl-)
- `SaltComposition` contains the ratio of the component in the salt

The ratio in NaCl is 1 for both ions. A more complex example would be 
trimagnesium phosphate (Mg3(PO4)2). Here the ratio would be 3 Mg to 2 
phosphates. So importing trimagnesium phosphate will lead to a `ChemicalCompound` 
consisting of the 2 `SaltCompositions` Mg and PO4 with the according ratio set.
  
See the [Release Repository][20] on [SonaType][21]. All releases are synced to
[Maven Central Repository][22] or available in the [Downloads Section][6]. 

----
## Introduction

Molecule Database Framework is a framework for rapidly creating applications 
that need to store and search for chemical structures in a relational database. 
It is based on [Spring-Data Framework][3] and uses the [Indigo Toolkit][4] and
[Bingo PostgreSQL Cartridge][5] for enabling chemistry features.

## Help and Support

See [Molecule Database Framework Wiki][12] for more detailed information and
code samples.

You can find JavaDoc of current release in the [Downloads Section][6].

There is also a simple demonstration Web Application called 
[MDF Simple Web App][16] which can be used as a reference.

## Installation / Usage

See [Molecule Database Framework Tutorial][14] for Installation instructions. 
You will need to install [PostgreSQL][15] and [Bingo PostgreSQL Cartridge][5] 
and create a new [Maven][23] Project. [Maven][23] is not required but it will 
make handling of dependencies much easier.

Note that the releases on SonaType and Maven Central are electronically signed.
To avoid too much clutter on the downloads section, it only contains the digital
signature for the jar containing the code but not for the sources or JavaDoc 
jars.

If you get the jar from the [Downloads Section][6]. You will also find the
digital signature for the jar and the the public key for verification. To
do this you will need a GPG distribution like [gpg4win][24].

See [Importing a public certificate][25] and [Checking a signature][26] for 
further information. Note that this verification is purley optional.

## Advantages

MDF is free as in libre and has no license costs. With MDF you can rapidly 
create free chemical structure search enabled database applications.

### Chemical Structure Search Features

MDF uses [Bingo PostgreSQL Cartridge][5] and exposed most of the cartridges 
functionality.

- Full Structure Search
- Sub Structure Search
- SMARTS Search
- Chemical Formula Search
- Similarity search (different algorithms like tanimoto, upper and lower bound)

These searches are offered through service methods that allow:

- Paging and Sorting
- Predicates (filters)

[QueryDSL][11] predicates allow to limit the structure search on other 
properties of the searched entity.

### Security

MDF is integrated with [Spring Security][7]. It offers method 
level security at the service layer. The security feature is optional and can be 
enabled in configuration.

### Configuration

MDF uses [Spring][2] in it's core and hence can very easily 
be used in tomcat. There is no need for a full blown Java EE Application server. 
If required MDF (actually Spring) can be configured to use JTA Transaction 
Manager, be it a standalone ([atomikos][8], [bitronix][9],...) or one provided 
by the Application Server.

### Rapid Development

Creating a basic chemical structure search enabled back-end is very quick, in 
minutes with a simple data model. You will spend by far the biggest amount of 
time developing the User Interface, be it web or client-based. For enabling 
chemistry you only need to extend the provided abstract classes (entity, 
repository, service) to which you add your custom data fields and search methods
and then storing, searching and chemical structure search will be automatically
be enabled. The developer does not require much chemistry knowledge.

## Contributors

Right now only me: Joos Kiener

## Contribute

Best contribution you can make is to add more tests, be it unit or integration 
tests. Coverage is far from complete and what is missing the most are
tests for "bad" input, eg. "testing for failure".

Unit Tests use mockito for mocking.

## Maven Repositories

Full Releases are available on the [Maven Central Repository][22].

If you wish to work with SNAPSHOT releases of MDF you need to add

```
#!xml
<repository>
	<id>sonatype-nexus-snapshots</id>
	<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</repository>
```

to your projects repositories.

For SNAPSHOT releases see the [SNAPSHOT Repository][13] on [SonaType][21]. 
See POM in src for all dependencies ([Spring-Data][3], [Hibernate][10],
others). Note: There is no guarantee that Source code and SNAPSHOT are in-sync.

### Dependencies

All Dependencies are managed by [Maven][23]. It is suggested you use [Maven][23] 
too or a build tool capable of using [Maven repositories][23] like 
[Apache Ivy](http://ant.apache.org/ivy/) or [Gradle](http://www.gradle.org/).

## Testing, Bugs and Stability

MDF should run fine. Most test are integration tests and it is hence assured 
that the components do work together in an intended way. What is missing is 
extensive testing with "bad" input.

Currently (Dec. 2013) I do not know any fully released productive application
that uses MDF. So it's fair to mention that you might run into early adopter 
issues.

[1]: https://bitbucket.org/kienerj/chemdb/overview
[2]: http://www.springsource.org
[3]: http://www.springsource.org/spring-data
[4]: http://ggasoftware.com/opensource/indigo
[5]: http://ggasoftware.com/opensource/bingo/user-manual-postgres
[6]: https://bitbucket.org/kienerj/moleculedatabaseframework/downloads
[7]: http://static.springsource.org/spring-security/site/
[8]: http://www.atomikos.com/
[9]: http://docs.codehaus.org/display/BTM/Home
[10]: http://www.hibernate.org
[11]: http://www.querydsl.com
[12]: https://bitbucket.org/kienerj/moleculedatabaseframework/wiki/Home
[13]: https://oss.sonatype.org/content/repositories/snapshots/org/bitbucket/kienerj/MoleculeDatabaseFramework/
[14]: https://bitbucket.org/kienerj/moleculedatabaseframework/wiki/Workflow%20Tutorial
[15]: http://www.postgresql.org
[16]: https://bitbucket.org/kienerj/mdfsimplewebapp
[18]: https://bitbucket.org/kienerj/moleculedatabaseframework/downloads/cdk-standard.jar
[19]: https://bitbucket.org/kienerj/moleculedatabaseframework/downloads/cdk-smiles-fixed.jar
[20]: https://oss.sonatype.org/content/repositories/releases/org/bitbucket/kienerj/moleculedatabaseframework/
[21]: http://www.sonatype.org/
[22]: http://search.maven.org/
[23]: http://maven.apache.org/
[24]: http://www.gpg4win.org/
[25]: http://www.gpg4win.org/doc/en/gpg4win-compendium_15.html
[26]: http://www.gpg4win.org/doc/en/gpg4win-compendium_24.html#id4