<source lang="bash">

<source lang="bash">

$ cd samples/livedb

$ cd samples/livedb

$ ant test

samples/livedb$ JAVA_HOME=/jdk-11 mvn clean test

</source>

</source>

This page documents my experiment showing how to do something similar in good old [[Java]]. Well, it is not old good [[Java]], but [[Java]]6. [[Java]]6 has been around for few years already, but it is common that good ideas take time. As a result we are only slowly recognizing how useful [[AnnotationProcessor]]s can be.

This page documents my experiment showing how to do something similar in good old [[Java]]. Well, it is not old good [[Java]], but [[Java]]6. [[Java]]6 has been around for few years already, but it is common that good ideas take time. As a result we are only slowly recognizing how useful [[AnnotationProcessor]]s can be.

== Screen Cast ==

== Screen Cast ==

Thanks [[Geertjan]] for recording this screen cast with me!

Thanks [[Geertjan]] for recording this screen cast with me!

== Get the sources ==

== Get the sources ==

== Extending IDEs ==

== Extending IDEs ==

The beauty of using [[AnnotationProcessor]]s is in their ability to naturally extend functionality of any IDE (that supports [[AnnotationProcessor]]s). As [[AnnotationProcessor]] [[API]] is part of [[JDK]]6, it is the most standard way to extend any [[Java]] IDE. For example there can be [[AnnotationProcessor]] that supports [[SQL]] syntax inside of the annotation strings.

The beauty of using [[AnnotationProcessor]]s is in their ability to naturally extend functionality of any IDE (that supports [[AnnotationProcessor]]s). As [[AnnotationProcessor]] [[API]] is part of [[JDK]]6, it is the most standard way to extend any [[Java]] IDE. For example there can be [[AnnotationProcessor]] that supports [[SQL]] syntax inside of the [[annotation]]'s strings.

[[Image:CompletionStatic.png]]

[[Image:CompletionStatic.png]]

== Extending IDEs ==

== Extending IDEs ==

The beauty of using [[AnnotationProcessor]]s is in their ability to naturally extend functionality of an IDE. In some sense [[AnnotationProcessor]] is a perfect [[API]] to extend any [[Java]] IDE. [[AnnotationProcessor]] can generate classes, resource files and can also add code completation items into your favorite IDE. As such there could even be code complation on inside of the string representing [[SQL]] statement to show you list of all available tables:

The beauty of using [[AnnotationProcessor]]s is in their ability to naturally extend functionality of any IDE (that supports [[AnnotationProcessor]]s). As [[AnnotationProcessor]] [[API]] is part of [[JDK]]6, it is the most standard way to extend any [[Java]] IDE. For example there can be [[AnnotationProcessor]] that supports [[SQL]] syntax inside of the annotation strings.

Still you are ''just'' writing a library. You don't need to understand any IDE's [[API]]s. This is all standard [[Java]]6 and there is no need for any hacks. [[AnnotationProcessor]]s turn [[Java]] into suitable meta-language for writing [[DSL]]s.

However providing static syntax is not all [[AnnotationProcessor]] can do. It can generate classes, resource files and can also add dynamic code completion items. It is possible to allow the processor to connect to live [[SQL]] database and show list of existing tables as suggestions for completion inside of the string representing [[SQL]] statement:

Indeed, writing the [[AnnotationProcessor]] needs a bit of skills, but it is not that much complex:

 

Still you are ''just'' writing a library. You don't need to understand any IDE's [[API]]s. This is all standard [[Java]]6 and there is no need for any hacks. [[AnnotationProcessor]]s turn [[Java]] into suitable meta-language for writing [[DSL]]s. Here is the code that provides static and dynamic code completion:

 

 

 

The code that generates the data access class follows. Indeed, writing such code requires a bit of understanding of the [[Java]] source model, but overall it is not that complex:

<source lang="java" snippet="livedb.processor"/>

<source lang="java" snippet="livedb.processor"/>

Just locate all packages annotated by ''@LiveDB'', reads the annotation data and use them to generate new [[Java]] source file. The file which later be compiled by the [[JavaC]] compiler.

Just locate all packages annotated by ''@LiveDB'', read the annotation data and use them to generate new [[Java]] source file. The generated file willl later be compiled by the [[JavaC]] compiler.

== Philosohical Aspects ==

== Philosohical Aspects ==

<comments/>

<comments/>

<source lang="bash">

<source lang="bash">

$ hg clone -r livedb http://source.apidesign.org/hg/apidesign/

$ hg clone http://source.apidesign.org/hg/apidesign/

$ cd apidesign

$ cd apidesign

$ hg pull

$ hg pull

== Extending IDEs ==

== Extending IDEs ==

The beauty of using [[AnnotationProcessor]]s is in their ability to naturally extend functionality of an IDE. In some sense [[AnnotationProcessor]] is a perfect [[API]] to extend any [[Java]] IDE.

The beauty of using [[AnnotationProcessor]]s is in their ability to naturally extend functionality of an IDE. In some sense [[AnnotationProcessor]] is a perfect [[API]] to extend any [[Java]] IDE. [[AnnotationProcessor]] can generate classes, resource files and can also add code completation items into your favorite IDE. As such there could even be code complation on inside of the string representing [[SQL]] statement to show you list of all available tables:

 

Still you are ''just'' writing a library. You don't need to understand any IDE's [[API]]s. This is all standard [[Java]]6 and there is no need for any hacks. [[AnnotationProcessor]]s turn [[Java]] into suitable meta-language for writing [[DSL]]s.

Still you are ''just'' writing a library. You don't need to understand any IDE's [[API]]s. This is all standard [[Java]]6 and there is no need for any hacks. [[AnnotationProcessor]]s turn [[Java]] into suitable meta-language for writing [[DSL]]s.

<source lang="java" snippet="livedb.processor"/>

<source lang="java" snippet="livedb.processor"/>

Most of the code is [[JDBC]] specific, the rest just locates all packages annotated by ''@LiveDB'', reads their data and uses them to generate new [[Java]] source file, which will be compiled later by the [[JavaC]] compiler.

Just locate all packages annotated by ''@LiveDB'', reads the annotation data and use them to generate new [[Java]] source file. The file which later be compiled by the [[JavaC]] compiler.

 

 

In some sense with an annotation like ''@LiveDB'' the structure of your database becomes part of your sources. But that is good, is not it? I really hate when a truth is spelled out at two different places (e.g. in [[Hibernate]] entity classes and also in the database schema). With [[LiveDB]] you just need a lightweight compile time database (like [[Derby]]) with the same structure as your deployment database being ready. The schema of such database is your definition of truth which remains at a single place.

<comments/>

<comments/>

== Screen Cast ==

== Screen Cast ==

As pictures speak thousands of words, you can now watch a screencast recorded to demonstrate the functionality of this project. Simply press play!

As picture easily expresses more than thousands of words ever could, you can now watch a screencast recorded to demonstrate the functionality of this project. Simply press play!

{{#ev:bliptv|3952631|600}}

{{#ev:bliptv|3952631|600}}

== Screen Cast ==

== Screen Cast ==

As visual impression is usually much stronger than thousands of words, you can now watch a screen cast recorded to demonstrate the functionality of this project. Just press play!

As pictures speak thousands of words, you can now watch a screencast recorded to demonstrate the functionality of this project. Simply press play!

{{#ev:bliptv|3952631|600}}

{{#ev:bliptv|3952631|600}}

The first thing you need to do to really play with the sample is to create your own database. Maybe you have one, maybe you need to create one. If you have [[NetBeans]] IDE then one is ready for you. Just start the [[Derby]] database as explained for example at [http://netbeans.org/kb/docs/ide/java-db.html JavaDB tutorial]. Create a table called AGE with two columns NAME and AGE.

The first thing you need to do to really play with the sample is to create your own database. Maybe you have one, maybe you need to create one. If you have [[NetBeans]] IDE then one is ready for you. Just start the [[Derby]] database as explained for example at [http://netbeans.org/kb/docs/ide/java-db.html JavaDB tutorial]. Create a table called AGE with two columns NAME and AGE.

Now open the ''samples/livedb'' project in [[NetBeans]] IDE 6.9. Version 6.9 is the necessary minimum, as it is the first version that provides superior support for [[AnnotationProcessor]]s.

<source lang="java" snippet="livedb.connection.annotation"/>

Open for example '''LiveDBTest.java'''. It uses class '''Age'''. That class is dynamically generated during compile time to reflect structure of the AGE table created before. But try for example code completion on:

As you can see this is compile time annotation, as such it needs to be processed by [[AnnotationProcessor]]. Indeed there is one in this project too, but rather than dicovering the magic, let's explore the ease of use: To access a database, just use the above given annotation on some package statement:

 

 

Of course you need to fill in proper connection credentials, and also the name of a class (''Age'' in the above case) that you wish to use to represent result of your ''query''. Done? If so, you are ready to use the class (which almost magically appears in your package). For example, in the following code snipptet, you can refer to the ''Age.query'' method and also access the fields of the class:

 

 

If you done things correctly, you have working access to live database. Everything compiles, runs and last, but not least, your IDE (if it is any good, like [[NetBeans]] IDE 6.9), will properly understood and use the on-the-fly generated ''Age'' class. Try for example code completion on:

<source lang="java">

<source lang="java">

</source>

</source>

You will correctly see fields representing individual rows in the t able. Moreover these fields have proper types (e.g. NAME is String, AGE is BigInteger). All of this is a result of simple use of the ''@LiveDB'' annotation in the ''package-info.java'' file:

You will correctly see fields representing individual rows in the t able. Moreover these fields have proper types (e.g. NAME is String, AGE is BigInteger). Feels like ''Java on Rails''? All of this is brought to you by the power of [[AnnotationProcessor]]s!

You can also modify the table structure by adding new column. As soon as you do it (and tell the IDE to refresh), you can immediatelly use the new fields in your code. Everything compiles. Btw. you need to tell the [[NetBeans]] IDE to refresh. You can either use new action ''Refresh All Metadata'' for that or you can step into ''package-info.java'', add an empty line and save the file.

@LiveDB(

classname="Age", password="j1", user="j1",

query="select * from APP.AGE",

package org.apidesign.livedb.example;

import org.apidesign.livedb.LiveDB;

 

The beauty of using [[AnnotationProcessor]]s is in their ability to naturally extend functionality of an IDE. In some sense [[AnnotationProcessor]] is a perfect [[API]] to extend any [[Java]] IDE.

 

Still you are ''just'' writing a library. You don't need to understand any IDE's [[API]]s. This is all standard [[Java]]6 and there is no need for any hacks. [[AnnotationProcessor]]s turn [[Java]] into suitable meta-language for writing [[DSL]]s.

 

== Modify the Table ==

<source lang="java" snippet="livedb.processor"/>

Now add new column to the table. Use it in the code. See if code completion sees it (probably not). If everything compiles (probably yes).

Most of the code is [[JDBC]] specific, the rest just locates all packages annotated by ''@LiveDB'', reads their data and uses them to generate new [[Java]] source file, which will be compiled later by the [[JavaC]] compiler.