[Pymerase-cvs-commit] Docs/output/modules CreateDBAPI.tex,NONE,1.1

[<ki...@us...>]

Update of /cvsroot/pymerase/Docs/output/modules
In directory sc8-pr-cvs1:/tmp/cvs-serv12779

Added Files:
	CreateDBAPI.tex 
Log Message:
first version of DBAPI docs


--- NEW FILE: CreateDBAPI.tex ---
% Pymerase Docs - CreateGraphvizUML
% Copyright (c) California Institute of Technology
%
% Authors: Brandon King
% $Revision: 1.1 $
% Modified $Date: 2003/05/06 22:52:03 $

\section{\cb CreateDBAPI}
\subsection{\cb Description}
CreateDBAPI generates a Python Database API to simplify the task of
creating Python programs which can access a database. For the DBAPI to
work, you need to have a database, you can either try to make a
compatible DBAPI for your existing database, or you can use the
CreateSQL output module to generate the SQL statements you need to
generate your database.

\subsection{\cb Useage}
Once you generate your DBAPI, you'll want to use it. Below is an
example of how to use your DBAPI.

\begin{verbatim}
#!/usr/bin/env python2.2

from YourAPI import DBSession

if __name__ == '__main__':
  dbs = DBSession(dsn='localhost',
                  database='dbName',
		  user='userName',
		  password=None)

  #######################################################
  # Getting Objects from the database
  #######################################################
  # Create ObjOne and ObjTwo objects
  #get all ObjectTypeOne objects
  objectTypeOneList = dbs.getAllObjects(dbs.ObjectTypeOne)

  #get all ObjectTypeTwo objects
  groupList = dbs.getAllObjects(dbs.Group)

  #get ObjectTypeOne with primary key/id of 1
  ObjTypeOneId1 = dbs.getObject(dbs.ObjectTypeOne, '1')

  #get ObjectTypeTwo objects with primary keys 1, 3, 4
  ObjTypeTwo134 = dbs.getObject(dbs.NameLinkPair,
                             ['1', '3', '4'])

  #get ObjectTypeOne by database field 'name'
  ObjTypeOneSomeNameList = dbs.getObjectWhere(dbs.ObjectTypeOne,
                                              'name = \'someName\'') 

  #get ObjectTypeTwo that is associated with 'ObjectTypeOne'
  # with name of 'someName'
  if len(ObjTypeOneSomeNameList) > 0:
    someNameObj = ObjTypeOneSomeNameList[0]
    objType2 = someNameObj.getObjectTypeTwo()

  #######################################################
  # Create new objects and associate them with eachother.
  #######################################################
  # Create one new ObjOne, and two new ObjTwo objects
  obj1 = dbs.ObjOne()
  obj2 = dbs.ObjTwo()
  obj2b = dbs.ObjTwo()
  
  #make an association between object one and two
  obj1.setObjTwo(obj2)

  #add another ObjTwo to obj1
  obj1.appendObjTwo(obj2b)

  #get all ObjTwo's associated with ObjOne
  obj2List = obj1.getObjTwo()
  print obj2List #--> [ obj2, obj2b ]

  #commit changes to database
  obj1.commit()
  
\end{verbatim}

\subsection{\cb Caveats}
\subsubsection{\cb Packages}
Pymerase has a partial implementation of a concept known in UML terms
as a Package. A Package allows you to define a portion of your model
which are closely related, so that it may be better organized.

The goal is to allow the generation of different packages with
CreateDBAPI. Instead of generating SomeAPI, Pymerase would generate
SomeAPI.Package1 and SomeAPI.Package2.

For now, Pymerase is only aware of one package. CreateDBAPI needs to
know about the package name inorder for the generated DBAPI to work
properly. If you are using parseXMI, it's defined by the UML namespace
and/or package name. If you are using parseGenexSchemaXML, it's
defined by the destination directory you supply when running Pymerase.