JSFillMethod.java

package clear.cdb.extjs.annotations;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Is used to generate incomplete set of Java and Ext JS classes
 * implementing CRUD data synchronization between a database and Ext JS UI; developer
 * is expected to override one of the generated classes to specify the actual methods of
 * selecting a list of records as well as creating/deleting/updating a record.
 * <p>
 *  <table class="innertable">
  
  	<tr>
  		<th>Parameter</th><th>Type</th><th>Required</th><th>Description</th>
  	</tr>
  	<tr>
  		<td><code>sync</code></td><td>Boolean</td><td>Optional</td><td>If set to <code>true</code> directs the code-generation script to support updates from the
 * Ext JS UI, in addition to pulling the data to Ext JS UI from Java. Default value is <code>true</code>.</td>
  	</tr>	
  	<tr>
  		<td><code>autoSyncEnabled</code></td><td>Boolean</td><td>Optional</td><td>If set to <code>true</code> directs the code generation script to include
 * push of the incoming updates to peer stores listening on the updates for the same result set. NOT IMPLEMENTED YET.
 *  </td>
  	</tr>	
  </table>
</p>  
 * <p>
 * Annotation <code>@JSFillMethod</code> allows to plug-in an existing Java class into Ext JS/Java data synchronization,
 * based on the <code>ChangeObject</code> interface <code>Clear.data.DirectStore</code>.
 * The method annotated by <code>@JSFillMethod</code> will be designated as a <code>read</code> method of the store's <code>api</code> config property.
 * Therefore it should return a collection of tuples, aka - data transfer objects(DTO) to be marhsalled to the store during the
 * Ext.Direct method invocation. When annotation parameter <code>sync</code> is <code>true</code>, code generation script 
 * creates additional four methods:
 * </p>
 * <pre>
 * 	public List<ChangeObject> [fill_method]_sync(List<ChangeObject>);
 * 	public List<ChangeObject> [fill_method]_deleteItems(List<ChangeObject>);
 * 	public List<ChangeObject> [fill_method]_updateItems(List<ChangeObject>);
 * 	public List<ChangeObject> [fill_method]_insertItems(List<ChangeObject>);
 * </pre>
 * <p>In turn, these generated methods along with the original [fill_method] from the annotated interface rely on the custom overloading
 * of the following methods:</p>
 * <pre>
 * 	public List<[DTOClassName]> [fill_method_name]() {
 * 	protected void [fill_method]_doCreate(ChangeObject changeObject) {
 * 	protected void [fill_method]_doUpdate(ChangeObject changeObject) {
 * 	protected void [fill_method]_doDelete(ChangeObject changeObject) {
 * </pre>
 <p>Ultimately, the developer has to subclass the class generated by ClearDataBuilder to provide the implementation for these methods.
 In anticipation of this, ClearDataBuilder generates a stub subclass as well, but only if the stub subclass is not 
 already present. Since stub subclass is never re-generated, all developer's changes are preserved intact.</p>
 *  <p>
 *  <b>Example</b>: The following method belongs to a class <code>com.farata.test.service.ICompanyService</code> and is annotated with
 *  (default) <code>sync=true</code> and <code>autoSyncEnabled=true</code>:
 * <pre>
 * 	@JSFillMethod(autoSyncEnabled=true)
 * 	List<com.farata.example.dto.CompanyDTO> getCompanies();
 *	</pre>
 * <p>
 *  As a result of the first-time code generation there will be a new class  - <code>com.farata.test.service.CompanyService</code>
 *  containing stubs - to be completed by the developer - for the following methods:</p>
 * <pre>
 * 	public List<CompanyDTO> getCompanies() {return null};
 * 	protected void getCompanies_doCreate(ChangeObject changeObject) {}
 * 	protected void getCompanies_doUpdate(ChangeObject changeObject) {}
 * 	protected void getCompanies_doDelete(ChangeObject changeObject) {}
 * </pre>
 * <p>
 *  This class will be descending from another class - <code>com.farata.test.service.generated._CompanyService</code> 
 *  with the following methods:</p>
 *  <pre>
 * 	public List<ChangeObject> getCompanies_sync(List<ChangeObject>);
 * 	public List<ChangeObject> getCompanies_deleteItems(List<ChangeObject>);
 * 	public List<ChangeObject> getCompanies_updateItems(List<ChangeObject>);
 * 	public List<ChangeObject> getCompanies_insertItems(List<ChangeObject>);
 * </pre>
 * <p>
 *  Developer will need to maintain only the derived class - <code>CompanyService</code>, expecting that <code>generated._CompanyService</code>
 *  will be regenerated by CDB on every build.
 *	</p>
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface JSFillMethod {
	boolean sync() default true;
	boolean autoSyncEnabled() default false;
}