# MiddleKit Documentation

Version 0.8.1
Webware for Python 0.8.1

# Introduction to MiddleKit

## Table of Contents

About the Middle Tier
About MiddleKit
Designing Your Objects
Providing Python Classes
Persisting to a SQL DB
Providing a default interface
Benefits of MiddleKit
What's Next?

## About the Middle Tier

In the world of application development, separating your software into modular components can be useful for:

- improved focus on a particular type of goal
- parallel development
- component swapping
- just plain ol' easier management

Often modern applications are divided into these three layers:

- data storage and serving
- middle objects
- interface

The data storage and serving is often a SQL database, a file system, an object-oriented (OO) database, an external data feed or some combination thereof. The interface is typically a web site, desktop GUI application or terminal interface.

What is left is the "middle tier" which is composed of objects that represent the concepts of the application. For example, an accounting application would have classes such as Account, Ledger and Statement. A customer service application would have Customer, Incident and LogEntry.

These objects are referred to differently by various authors:

- middle objects
- domain objects
- business objects
- problem space objects
- concept objects

There is a lot of value in building these middle objects for their own sake, regardless of storage and interface. The most obvious benefit is the ability to later change storage and interface strategies without having to rewrite the middle objects. For example, the accounting system might start with a GUI interface but later be migrated to a web interface. Or the storage might be changed from a SQL DB to an OO DB.

Another benefit is that mature third party tools can often by aquired that work with the storage directly for queries, browsing and reporting.

As with objects in general, both the data and the methods of the middle objects need to be considered. What information will the object store? For example, an Account has a name, has a balance and is either a credit or debit account. Also, what methods will an account provide? For example, an Account can provide credit(amount) and debit(amount) methods to adjust its balance.

Note that other types of applications can be constructed using the middle tier. For example, in addition to a web interface, a monitoring program could be created to analyze data and send e-mails alerts to the appropriate users. A reporting application could be created to periodically generate static "for-the-record" HTML reports which are then stored in a known location.

## About MiddleKit

MiddleKit is a Webware component designed to encourage the use of and ease development of the middle tier. It provides:

- A useful, but light weight methodology for designing the middle tier
- Automatic persistence to popular SQL databases
- A uniform web interface for browsing middle objects

Warning: This document is light on examples and does not show you how to implement the ideas discussed. That's intentional; this document lays down the motivations and benefits of the MiddleKit approach. After reading this, go on to the Quick Start Guide where your hands will get plenty dirty. After that, read through the User's Guide to round out your knowledge of MiddleKit.

Or read the Quick Start Guide first if you like and come back here to clean your hands off. Be especially sure to revisit this introduction if at the end of the Quick Start you're wondering "what's the point?"

### Designing Your Objects

The "methodology" is really quite simple and consists of creating a data-centric object model in a spreadsheet. Data-centric means that the model is more concerned with data attributes rather than methods. Object model simply means a list of the Python classes, who they inherit from, and their attributes.

Note that these spreadsheets are actually comma separated value (CSV) files can be read and written with almost any spreadsheet program. Also, because CSV files are text files, they are amenable to text editing, source code control, etc.

Note that MiddleKit accepts all the following items of information about attributes:

- name
- type
- default value
- min and max
- required

MiddleKit can use this information to provide better Python and SQL support that will save you from headaches and work. MiddleKit also tracks superclasses and which classes are abstract, which can provide for further design time and run time checks.

And you can use the object model to stay in tune with what information is being tracked in your application. You may even find it useful to bring the object model to meetings with end users, either for your reference or their direct inspection.

### Providing Python Classes

MiddleKit uses the object model to provide Python classes to help bootstrap your project. There are actually two classes: a stub for your home grown code and a generated class for MiddleKit's generated code. For example, the Account class in the object model will produce an Account.py for your editing pleasure which inherits from GenAccount.py, which will get regenerated every time you change your model (which will be plenty).

In Account.py, you can add, remove and edit code to your heart's content. MiddleKit generates this stub if it does not exist, but will never overwrite it.

In GenAccount.py, there will be access methods for the attributes filled with assertions that you haven't violated the attributes definitions. For example, if an attribute is required, you cannot set its value to None without raising an exception. You also cannot set attributes to an incorrect type. There are additional methods depending on the type of attribute. For example, list attributes get an addToBars() method.

All of these classes ultimately inherit from MiddleObject which provides some useful methods such as:

isChanged() | Whether or not the object has been changed since the last time in-memory changes were saved to the persistent store.
store() | Returns a reference to the object store the object belongs to.
klass() | Returns the MiddleKit class definition the object was created from.
dumpAttrs() | Writes the attributes in a readable format for debugging purposes.

### Persisting to a SQL DB

From the object model, MiddleKit is able to provide an abstract interface for persistence and a concrete implementation of SQL DB persistence. Once your model is created, you get this practically for "free". In supporting SQL, MiddleKit does two things:

At design time: | MiddleKit generates the SQL CREATE statements needed to store the objects you have described. (And also the SQL INSERT statements if you provided sample data in another CSV file.)
At run time: | MiddleKit interacts with a live SQL database to insert, update and delete the SQL data corresponding to your objects. All on your behalf, largely behind the scenes.

As a programmer using MiddleKit you will not need to know or understand SQL. Your responsibilities will be to:

Connect: | Provide the connection information needed by the MiddleKit object store to connect to the persistent store (typically a SQL database).
Access: | Use the accessor methods of your middle objects to get and set attributes.
Save: | Periodically invoke store.saveChanges() in order to commit changes in memory that have not yet been persisted.

There is a notable exception concerning SQL driven by the fact that queries are typically faster on the SQL server side, than on the client side. When fetching objects through a MiddleKit object store that is connected to a database, you can pass SELECT clauses such as WHERE and ORDER BY. The User's Guide has more information on this topic under @@.

MiddleKit could also be extended to persist to other storage facilities such as the file system or the OODB. Switching storage facilities, whether it's a particular database, or a different type of storage altogether should require nothing more than configuration. (Again the notable exception: if you have used SELECT clauses for server side queries, your new storage facility must support those, or your store must translate them to something supported, or you must translate them in your application.)

Note that Python's interface for databases, DB API 2.0, does not provide SQL statement independence. Only connections and cursors are standardized. The fact is that SQL varies from database to database, although you'll find that most if not all of your SELECT clauses will be portable.

MiddleKit will also load sample middle object data from a spreadsheet that your provide. Again, if you change storage strategies, you will not need to update your sample data.

### Providing a default interface

MiddleKit provides a WebKit application, called the MKBrowser, that can browse any middle kit object store when provided the object model. The application accomplishes this by using MiddleKit to deal strictly with Python objects.

MKBrowser is great for getting you a first cut, usable interface to interact with your objects. Later, you will likely build a customized interface from scratch, according to the needs of your users.

Currently MKBrowser only provides viewing, but a future version will also provide editing and searching.

## Benefits of MiddleKit

In summary, the benefits of using MiddleKit are:

- Focus on the middle tier
  - Improve modularity.
  - Increased ease in changing storage and interface strategies.
  - Invest more time in designing your objects

- Provide an object model
  - Enables MiddleKit to automate many tasks
  - Provides precise documentation on classes and attributes
  - Enhances Python programming with stronger notions of type and range checking.

- Python code generation
  - Automatic fetching and unarchiving of related objects.
  - Assertions:
    - type checking
    - range checking
    - is-required checking

- SQL database persistence
  - Ability to switch SQL database vendors with little or no source code changes.
  - Use SQL tools:
    - Interactive prompt
    - GUI front ends
    - Web front ends
    - Reporting tools

- Web interface
  - Immediately browser and interact with the objects in your application through the web.

## What's Next?

Your next step is to read the Quick Start Guide which shows step-by-step how to create and use an object model. You could even start building your custom application by following the guide as you read.