MiG InfoCom Calendar DBConnect User Manual

MiG InfoCom AB

DBConnect Guide

______________________________________________________________

Release 1.2

DBConnect Guide Page 1 / 25

MiG InfoCom AB

MiG InfoCom AB
S:t Olofsgatan 28a
753 32 Uppsala
Sweden

www.miginfocom.com

COPYRIGHT © MiG InfoCom AB.
All rights reserved.

Java is a trademark registered ® to Sun Microsystems.

http://java.sun.com

DBConnect Guide Page 2 / 25

MiG InfoCom AB

Table of Contents

MiG Calendar Tutorial.................................................. 5

Preface............................................................................................... 5

Resources and Developer Support................................................. 5

Contacting Support directly via Email...................................................5

Submit a support ticket.........................................................................5

MiG Calendar Product Site.................................................................. 5

Bug Reports......................................................................................... 6

How to read this Document............................................................. 6

Setting up DBConnect for usage..................................................... 6

Classpath............................................................................................. 6

MiG Calendar Component................................................................... 6

Supported Databases and JDBC Drivers............................................. 6

Overview............................................................................................ 7

Database Updates............................................................................... 7

Database Reads.................................................................................. 7

ActivityDepository and CategoryDepository......................................... 7

The DBConnect Architecture................................................................7

Layered Architecture............................................................................ 8

Multiple Databases...............................................................................9

Multiple Clients................................................................................... 10

Setting Up the Property Mappings................................................ 10

What is a Property?............................................................................10

Property Mappings............................................................................. 10

Load/Save Mappings to File............................................................... 11

Mandatory Properties......................................................................... 11

Custom and Non-mandatory Properties............................................. 14

Update Tables for Increased Performance......................................... 14

DBConnect Guide Page 3 / 25

MiG InfoCom AB

Database Connection......................................................................... 15

Example Database Mapping.............................................................. 15

Using MiG Calendar the Correct Way............................................15

Event Types....................................................................................... 15

Miscellaneous Topics..................................................................... 16

Logging.............................................................................................. 16

Creating a Database from the Mappings............................................17

Deleting Table Data............................................................................ 17

Monitoring the Database Queue........................................................ 18

Filtering What to Synchronize............................................................ 18

Polling and Setting Auto-poll Interval.................................................18

Auto Write.......................................................................................... 18

Managing Shutdown and Flushing..................................................... 18

Queue Action Coalescing................................................................... 19

Pausing and Resuming the Database Queue/synchronizer...............19

Adapting to Other Databases (DBTypeAdapter)................................20

Listening for Concurrent Update Events............................................20

Listening for Exceptions..................................................................... 20

Loading only Visible Activities............................................................ 21

Custom Properties in Activities or Categories....................................21

Persisting your custom data types..................................................... 22

Troubleshooting................................................................................. 25

General Suggestions and Tips........................................................... 25

DBConnect Guide Page 4 / 25

MiG InfoCom AB

MiG Calendar Tutorial

Preface

This document aims at providing enough information to get started
using the DBConnect plugin with the MiG Calendar component. The

MiG Calendar Tutorial contains information on how the component is

structured including a overview of its different parts.

The MiG Calendar Technical Specification (API JavaDoc) will provide
details and should be used as a reference. It can be found at the web
site indicated below and should also normally be installed adjacent to
this document.

Many IDE:s (Integrated Development Environment) of today have
good support for inline help using JavaDocs. The standard HTML
JavaDocs for the MiG Calendar component is installed by default and
can also be obtained from the site as described below. We highly
recommend using this feature as it increases productively when
creating applications with this component.

Although all developers independent of prior experience can benefit
from reading this document, general knowledge of the standard Java
API and OOP (Object Oriented Programming) will help understand
some of the details and why they are implemented in a certain way.

Resources and Developer Support

MiG InfoCom AB provides support through email and the online
forums. Information and updated tutorials will be made available on
the MiG Calendar product site

Contacting Support directly via Email

[e-mail]

Submit a support ticket

http://www.migcalendar.com/support.php

MiG Calendar Product Site

www.migcalendar.com

DBConnect Guide Page 5 / 25

MiG InfoCom AB

Bug Reports

Please submit a support ticket.

How to read this Document

This guide is written to give an understanding on how to use
DBConnect. This is not an API reference. You should have the
JavaDoc API reference open at the same time as reading this as a
reference for method signatures.

There are example source code installed adjacent to this document. It
should be used as a reference as well.

Setting up DBConnect for usage

Classpath

In order to use DBConnect your application needs to find it. How to do
this depends entirely on you environment but normally you add it to
your classpath, possibly in the project settings in your IDE. The file to

add to the classpath is dbconnect.jar

MiG Calendar Component

In addition to adding the DBConnect to your classpath you also need
to setup the MiG Calendar Component for use. How to do this is
specified in the Getting Started Guide.

Supported Databases and JDBC Drivers

DBConnect has be developed with, and tested against, the following
databases and JDBC drivers:

Microsoft SQL Server 2000 – jTDS 1.2, MS JDBC 2000 and MS JDBC
2005 reference JDBC drivers. jTDS and MS JDBC 2005 driver are
highly recommended.

PostgreSQL - Their own provided JDBC driver.

MySQL (4.1 and up) - Their own provided JDBC driver.

IBM DB2 - Their own provided JDBC driver.

HSQLDB 1.8 - Their own provided JDBC driver.

Oracle 9 - Their own provided Thin JDBC driver.

DBConnect Guide Page 6 / 25

MiG InfoCom AB

It should be noted that it is the exact same Java code that is run for
the different databases*. Standard SQL is used and JDBC
functionality that is supported by all databases/drivers above. This
means that it is quite probable that other databases is working as well.
For adding a database to the supported list, after thorough testing,

contact [e-mail].

* Oracle returns all numeric column values as BigDecimal. This is why an

OracleAdapter is included. The code for creating the database, which is normally

only done for testing purposes, has slightly different defaults as well.

Overview

Database Updates

DBConnect is monitoring changes in MiG Calendar's

ActivityDepository and CategoryDepository classes

and when changes are discovered converts that change to a database
action that is put in a queue. There is a separate thread that is reading
from this queue and commits the actual changes to the database.

Database Reads

The database is read in the same way it is written. A read action is put
on the database queue and when it is its turn, which is normally right
away, data are read from the database and put in the corresponding
depository in memory.

ActivityDepository and CategoryDepository

MiG Calendar has two central classes that holds activities (e.g.
events, todos and tasks) and categories (e.g. priorities, activity
owner(s), basically any way you would like to “tag” activities)
respectively. This makes managing entities (Activities and Categories)
simple for the application developer. These two classes are also the
focal point for DBConnect. The advantage with this approach is that
since these two classes are used as the in-memory storage for
entities in all MiG Calendar applications, there is little, if any, changes
that are needed to make the (your) application synchronization
aware.

The DBConnect Architecture

At the lowest level a property of the activity/category is mapped
to to a column or an XML element/attribute with a

PropertyMapping object. All property mappings that are
intended for one database table or XML element are then

DBConnect Guide Page 7 / 25

MiG InfoCom AB

collected into one PropertyMappingList object. To that
PropertyMappingList object are optionally also a special

update table associated that has its own, very simple,
UpdateMapping. One can also connect a number if mappings

to other tables in the form of IDToManyPropertyMappings.
These are for instance to map a single Activity to several

Categories though the use of a join table. Both of these features
are explained further below.

A DataProvider is wrapped around the

PropertyMappingList object and, for use with a database, a
ConnectionProvider are included as well. The
DataProvider has all the information on how to read/write

properties from the activities/categories and load/save it to a
backing store. For database persistence a DBDataProvider is

used and you can for instance use an XMLDataProvider to
read/write from an XML file (XML implementation not provided

with 1.0).

We must also add the more high level functionality of monitoring
the ActivityDepository and CategoryDepository as

well as provide background processing in a worker
thread/queue. This functionality is provided by the

DataSynchronizer which normally is an
ActivityDataSynchronizer or a
CategoryDataSynchronizer.

From that synchronizer you control almost every aspect of the
DBConnect plugin.

Layered Architecture

DBConnect is created in a layered architecture. You can choose
just to configure it or to add you own persistence delegates
instead of the ones provided by the plugin.

DBConnect Guide Page 8 / 25