ZINRO - A RCP, OSGI and SPRING based framework for developing scalable client server applications

1. ZINRO
A Eclipse / OSGI based Framework for
Information Management Systems

2. ZINRO is an OSGI/RCP based framework for developing Information Management
Systems in a Client / Server Architecture with a simplified approach towards handling
Business Entities. It provides application developers with a rich set of OSGI Services, UI
Elements, Eclipse Extensions and functions to focus on business logic while minimizing
labor intensive recurring tasks.
Some of the “Out of the box” features provided by Zinro are
•Entity Relationship Management
•Entity Validation
•Cross Bundle Transactions
•Annotation based Controlling
•UI Creation
•Widgets
•Report Infrastructure
•User and Group Management
•Resource and Access Control Management
•Login and Session Management
•License Management
•Server Side Spring Integration
•Client / Server Messaging
•Scheduled Job Publication
•RMI Publication
•Database Update mechanism on bundle
updates

3. Zinro Base Models
At the heart of the Zinro Framework are the base model classes
extending JPA entities. All Zinro Models must extend from one of the
base model class
AbstractView
AbstractIdView
AbstractModel
RelationalModel StatefulModel
…
…
…
Basic view Zinro Model Hierarchy
*Not all classes included

4. Relationships
Zinro provides its own relationship handling mechanism. Relationships are defined on Model
Classes using Annotations.
•Association - All classes extending AbstractModel can have 1-1 relationships with other
model classes defined using @ModelAssociation annotation
•One to Many (Parent – Child) – All classes extending AbstractRelationModel can map
multiple 1-N relationships to classes extending AbtractDependentModel using the
@OneToManyMap annotation. AbtractDependentModels objects are not instantiated
with “new” rather created using Framework Services
•Many to Many - All classes extending AbstractRelationModel can map multiple N-N
relationships to classes extending AbstractRelationModel using the @ManyToManyMap
annotation. The framework provides an internal class (and a corresponding table) for
holding the N-N relationship therefore no other object is required
•All primary and foreign keys are managed by Zinro

5. Zinro Client Services
Model Management / Handling is achieved through Zinro client services, a set of OSGI services,
published by the framework. Most methods of the services are type safe
Model Service
public <A extends AbstractModel> A loadModel(Class<A> type, Long id) throws ZfmException;
e.g. MyClass myClass = modelService.loadModel(MyClass.class,10000010L);
...
public <A extends AbstractView> List<A> getList(Class<A> modelClass,ListParam listParam) throws ZfmException;
e.g. List<MyClass> myClassList = modelService.getList(MyClass.class, new ListParam(“m.name=?1”, Collections.singletonList(“john”)));
...
public <A extends AbstractModel> A getAssociation(AbstractModel model, Class<A> clazz) throws ZfmException;
Relational Service
public <A extends IDependent> A createChild(AbstractRelationalModel arModel,Class<A> childClass) throws ZfmException;
e.g. MyChild child = relationalService.createChild(myClass,MyChild.class);
...
public void removeChild(AbstractRelationalModel arModel, AbstractModel rel);
...
public <A extends AbstractModel> List<A> fillRelationList(AbstractRelationalModel arModel, Class<A> relationClass)throws ZfmException;
Used for both 1-N and N-N relationships (loads from DB)
public <A extends AbstractModel> List<A> getCurrentRelationList(AbstractRelationalModel arModel, Class<A> relationClass);
Used for both 1-N and N-N relationships for already loaded objects

6. Transaction Service
Classes implementing the interface <IPersistant> (i.e. RelationalModel & StatefuleModel) can only be
directly saved or deleted. Dependent relational objects are automatically saved, deleted accordingly
public void execute(IPersistant model) throws ZfmException;
...
Objects from different independent bundles can take part in a transaction
public void execute(List<IPersistant> modelList) throws ZfmException;
e.g. list.add(myObjectFromBundleA);
list.add(myObjectFromBundleB);
transactionService.execute(list);
// either will commit all or rollback with exception
Other Services
Framework Service – Service for accessing user session, RMI registry, scheduled jobs, messages
and other resources
Security Service – Service for checking resource access against users / groups. This service is used
for all operations of Model, Relational and Transaction Services
Preferences Service – A service for handling DB persisted preferences provided by Zinro

7. Model Dialog
Model Dialog facilitates developers by implicitly providing features like
Saving, Deleting, Traversing, Searching and Filtering for Zinro Model
Class
The example used in the presentation is a “Question” model from an Examination System
To create a model dialog, an entry is added to the “com.bnv.zinro.ui.dialogs” extension provided
by the Zinro Framework

8. The Dialog Composite
Toolbar provided by Model Dialog
@Override
public Composite
createContents(Composite parent);
// creating UI
@Override
public void inputChanged(final IDialogInput
input);
// Called during traversing
Show dialog function
ZinroUI.showDialog(“com.bnv.zinro.caalic.question”,ne
w DialogInput());
The dialog composite implements IDialogComposite (from Zinro)

9. @ReportElement Annotation
@Entity
@Table(name="CAA_QUESTION")
@BundleLink("caamodel")
@OneToManyMaps({
@OneToManyMap(mapClass=McqAnswer.class),
@OneToManyMap(mapClass=FitbAnswer.class),
@OneToManyMap(mapClass=BoolAnswer.class),
@OneToManyMap(mapClass=ModelBlob.class),
})
@SecurityContext(Question.class)
public class Question extends RelationalModel {
@Column(name="TITLE",length=4000)
@Validation(alias="Question Text",required=true,max=4000)
@ReportElement(name="Question Text”,zlist=true,index=0,width=400)
protected String title;
@Column(name="MARKS")
@Validation(alias="Marks",required=true)
@ReportElement(name="Marks”,zlist=true,index=2)
protected Short marks;
@Column(name="REF",length=100)
@Validation(alias="Ref",max=100)
@ReportElement(name="Ref”,zlist=true,index=1)
protected String ref;
...
@ReportElement annotation is used to control the attribute listing in different UI elements. In the
model dialog context it controls the list view and search filter.
List of @ReportElement attributes

10. • The list provides navigation control like next, previous,
first, last page, Page Size and displays total records and
current pointer
Model List and Filter
• Clicking the Apply button will filter the list.
Double clicking on a element would close the list
and populate Model Dialog with the selected
model.
• The filter would also hold its state when re-
opened next time
List and Filter implicitly created by annotating member variables with @ReportElement

11. Reports
Reports in Zinro are designed as Jasper Reports and a backing class
extending JREditorInput (Zinro) is required for providing content
Reports are viewed in the editor
area of the workbench.
JREditorInput implements
IEditorInput from og.eclipse.ui.
The Zinro Report UI interface uses
SWT Jasper Viewer for showing
reports with a few additions such as
filter, clear and refresh buttons
The method that needs to be
overridden in JREditorInput is
@Override
protected JRDataSource
getDataSource(JRModifier
jrModifier, boolean refresh) throws
ZfmException

12. ...
<report name="Question List" category="Exam">
<file>paper/question.jasper</file>
<provider>com.bnv.zinro.caalic.paper.reports.QuestionInput</provider>
<security-context></security-context>
<description>Question List</description>
</report>
<report name="Question Group List" category="Exam">
<file>paper/question-group.jasper</file>
<provider>com.bnv.zinro.caalic.paper.reports.QuestionGroupInput</provider>
<security-context></security-context>
<description>Question Group List</description>
</report>
<report name="Question Detail List" category="Exam">
<file>paper/question-detail.jasper</file>
<provider>com.bnv.zinro.caalic.paper.reports.QuestionDetailInput</provider>
<security-context></security-context>
<description>Question Detail List</description>
</report>
...
Reports Dialog
In addition to linking reports to Menu Items, Zinro provides an All Reports dialog with proper
categorization and description of reports
Config.xml excerpt ( Reports Dialog
populates from this content )

13. Report Filter
Report filter is provided by Zinro reading the same @ReportElement annotation. Values from the
filter are passed to the JREditorInput class as an argument

14. More Zinro Widgets
StructuredCombo
Provides a combo like control with multiple columns and is filtered on key stroke. If a Zinro Model is
used a content provider, the control is generated on the fly using @ReportElement annotation
Masked TextBox
A Key validated text box. The key is validated against the mask provided. E.g. the mask below is
NNN-NNNN-NNN-NNN
N as Number, A as character, Z as alphanumeric and S as symbol are implemented by default. Users
can extend their own types of masks

15. Grids
Zinro Grids populated with different providers and cell editors

16. Access Control
Zinro provides “out of the box” access control for models and other
resources as a combination of functions, UI Elements and services
Defining a Security Context
•Models can explicitly be annotated with @SecurityContext defining a security class which
extends AbstractView
•If no @SecurityContext is provided, the class itself is considered the security context class
•Other attributes of @SecurityContext are bypassRead, bypassModify and embeddable
@Entity
@Table(name=”CATL_AIRLINE")
@BundleLink(”catalyst")
@Audit(alias="Airline",storeState=true)
@SecurityContext(value=Airline.class,bypassRead=true)
public class Airline extends Vendor {

17. Publishing a Security Context
Security Context is published using the “com.bnv.zinro.core.security” extension. A friendly
for the resources is defined. The extension also caters for grouping of security contexts.
Class Resource
A security context class based resource

18. Configuration Resource
The other type of is the Configuration Resource. It takes a String based code as an
identifier

19. Published Resource View

20. User and Group Management
Zinro provides User and Group Management. User can belong to any number of groups.
Groups have a Priority Level which is unique and inverse i.e. higher the number lower the
priority. The system access policy is deny allow (whitelist)

21. Brining it all together - Resource Access
Access Control Dialog
provided by Zinro provides a
list of Users and Groups
assigned to a Resource

22. Users and Groups could be
added and removed from a
resource

23. Selected User / Group on a
Access Control Dialog displays
the corresponding permissions
in the bottom area
Create + View is allowed
whereas Modify + Remove is
denied

24. Zinro Login Dialog
A DES encrypted Token is generated and returned by the server for login which is passed and
validated in every called made to the server by the client application

25. Access Controlled Menu and Toolbar Items
A Command Handler created by extending ZinroSecureHandler class, manages
the enabling and disabling of menu items (and commands) according to the user
rights

26. Security Service
All Zinro services internally call Zinro Security Service for user access and permissions. If there is an
error, the user is notified. Below is the exception thrown by the framework after the user tried to delete
an entity from Model Dialog without appropriate permissions

27. License Management
Zinro also provides license management on model bundles separately. A bundle could
choose whether or not to be licensed.
If there are licensed bundles and the license is missing or invalid, a registration window is
popped. For registration, a MAC Address is bound to a license so that a license could be
revalidated on the same machine. A Zinro License Server Application is required to validate
the licenses
Installed Version
License Version

28. Installed License Details

29. Server Side Zinro
Zinro Server is an OSGI application running with Spring, JPA and Zinro
Model bundles. The server manages all database activity and provides
services to other Zinro bundles
Sample Server Arguments
-Dosgi.noShutdown=true
-Declipse.ignoreApp=true
-Dosgi.parentClassloader=app
-javaagent:${workspace_loc}/TargetPlatforms/agents/spring-agent-
2.5.4.jar
-Dzinro.product=catalyst
-Dzinro.conf=/Users/farooq/Reference/zinro/h2d.conf
-Dzinro.log4jPath=../log4j.properties
-Dosgi.install.area=${workspace_loc}/../tmp
A typical zinro.conf file looks like
Url=jdbc:h2:tcp://192.168.0.2:9092/../CATALYST_5;CIPHER=XTEA
User=sa
#Password=
PoolSize=4
Dialect=org.hibernate.dialect.H2Dialect
NodeId=8
NodeName=SRV-CATALYST
Uri=192.168.0.15
Port=27879
NodeDescription=Test Machine for Catalyst Server
TimeDifference=0
Typical Zinro Model Bundle Structure

30. Publishing RMI Objects
RMI objects are published on the same registry simply by creating a Spring Bean of class
implementing Remote and adding to Zinro’s RMI publisher
<!–- bean implementing java.rmi.Remote 
<bean name="searchManager" class="com.bnv.zinro.catalyst.remote.SearchManager"/>
<!–- OSGI service reference to Zinro RMI Manager -
<osgi:reference id="rmiManager"
interface="com.bnv.zinro.core.nodelayer.IRmiManager"/>
<!–- Zinro RMI Publisher bean instance publishing Remote items in Map -
<bean name="rmiPublisher" class="com.bnv.zinro.core.nodelayer.RmiPublisher"
init-method="publish">
<constructor-arg ref="rmiManager"/>
<property name="rmiObjectMap">
<map>
<entry key="searchManager" value-ref="searchManager"/>
</map>
</property>
</bean>
Client Side Zinro
ISearchManager searchManager = frameworkService().
getRegistry.lookup("searchManager");

31. Scheduled Jobs
Zinro Schedule Jobs wrap Quarts jobs to be easily used in the Zinro’s client / server environment.
In order to create a job, the class must extend Zinro AbstractJob and override
@Override
protected Object execute(JobDataMap jobDataMap, int monitorId, SealedObject token)
throws ZfmException
Jobs are published as by creating a Spring Bean of the job and publish it with Zinro’s Job Publisher
<!–- Bean extending AbstractJob -
<bean id="openingBalanceJob" class="com.bnv.zinro.catalyst.remote.OpeningBalanceJob”/>
<!–- OSGI service reference to Zinro Job Manager -
<osgi:reference id="jobManager" interface="com.bnv.zinro.core.nodelayer.IJobManager"/>
<!–- Zinro Job Publisher -
<bean name="jobPublisher" class="com.bnv.zinro.core.nodelayer.JobPublisher"
init-method="publish">
<constructor-arg ref="jobManager"/>
<property name="jobList">
<list>
<ref bean="openingBalanceJob"/>
</list>
</property>
</bean>

32. There are 3 ways to call a Zinro Schedule Job from the client
Immediate
public int scheduleJob(String jobClass, Map<String,Object> dataMap)
Delayed
public void scheduleJob(String jobClass, Map<String,Object> dataMap,long start)
Cron
public void scheduleJob(String jobClass, Map<String,Object> dataMap,String cronSpecs)
The framework handles the persistence of delayed and cron jobs to the database

33. Database Updates
Zinro provides an extension “com.bnv.zinro.core.dbUpdate” for updates to the database when a
newer version of the bundle is installed.
The basic element of the extension is a update version number. It sequential executes the 4 types of
operations SQL, TABLE, UPDATE_CLASS and VIEW. The framework stores the last db update version.
Optionally, Zinro Model bundles store VIEW and default data SQL in xml files

34. • Live application DEMO