org.proteios.core
Class DbControl

java.lang.Object
  org.proteios.core.DbControl

public final class DbControl
extends Object

A DbControl object is the main object used for communicating with the database. It contains methods for saving and deleting items, handling transactions, etc. DbControl objects are created by the SessionControl.newDbControl() method.

Version:

2.0

Author:

Nicklas, Samuel

Last modified

$Date: 2009-04-09 08:48:11 +0200 (Thu, 09 Apr 2009) $

Method Summary

void	close() Close the connection to the database.
void	commit() Commit all changes made to items and close the connection to the database.
void	deleteItem(BasicItem item) Schedule an existing item to be deleted from the database.
void	detachItem(BasicItem item) Detach an item from this DbControl.
void	disconnect() Temporarily disconnect from the database.
protected void	finalize() Clean up if a bad client application forgot to close the connection.
SessionControl	getSessionControl() Get the SessionControl object that owns this DbControl object.
void	initCollection(BasicItem item, String collectionName) Initialise a collection on an item.
boolean	isClosed() Check if the connection to the database has been closed.
boolean	isConnected() Checks if there is an active connection to the database or not.
void	reattachItem(BasicItem item) Reattach a detached item from this DbControl.
void	reconnect() Reconnects to the database after a disconnect().
void	saveItem(BasicItem item) Schedule a new item to be saved in the database.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isClosed

public boolean isClosed()

Check if the connection to the database has been closed. To get a new connection, you must create a new DbControl object.

Returns:

TRUE if the connection is closed, FALSE otherwise

See Also:

SessionControl.newDbControl()

getSessionControl

public SessionControl getSessionControl()

Get the SessionControl object that owns this DbControl object.

Returns:

a SessionControl object

disconnect

public void disconnect()
                throws BaseException

Temporarily disconnect from the database. Uncommitted changes of regular items are not lost, but you must reconnect() before calling commit(). If you have used batch items, you should call commit() or you will lose everything that has already been BasicBatcher.flush():ed to the database.

Throws:

BaseException

reconnect

public void reconnect()
               throws BaseException

Reconnects to the database after a disconnect().

Throws:

BaseException

isConnected

public boolean isConnected()

Checks if there is an active connection to the database or not.

close

public void close()

Close the connection to the database. Uncommitted changes will be rolled back. If the connection is already closed this method does nothing. Any errors in this method are written to the log file. After calling this method the DbControl cannot be used anymore.

commit

public void commit()
            throws BaseException

Commit all changes made to items and close the connection to the database. If there is an error, a rollback is issued and the connection is closed.

Throws:

BaseException - If there is an error

saveItem

public void saveItem(BasicItem item)
              throws PermissionDeniedException,
                     ItemAlreadyExistsException,
                     BaseException

Schedule a new item to be saved in the database. The item is saved the next time the commit() method is called.

Parameters:

item - The item to be saved

Throws:

PermissionDeniedException - If the logged in user doesn't have create permission

ItemAlreadyExistsException - If the item already exists in the database

BaseException - If there is another error

deleteItem

public void deleteItem(BasicItem item)
                throws PermissionDeniedException,
                       ItemNotFoundException,
                       BaseException

Schedule an existing item to be deleted from the database. The item is deleted the next time the commit() method is called.

Parameters:

item - The item to be deleted

Throws:

PermissionDeniedException - If the logged in user doesn't have delete permission

ItemNotFoundException - If the item doesn't exist in the database

BaseException - If there is another error

detachItem

public void detachItem(BasicItem item)
                throws BaseException

Detach an item from this DbControl. The detached item will no longer be managed and changes will not be saved to the database. For some items, certain operations are forbidden for detached items. For example you are not allowed to upload files to File items.

Parameters:

item - The item to be detached

Throws:

BaseException - If there is an error

See Also:

reattachItem(BasicItem)

reattachItem

public void reattachItem(BasicItem item)
                  throws PermissionDeniedException,
                         ItemNotFoundException,
                         BaseException

Reattach a detached item from this DbControl. If the reattached already exists in the database it will be managed and changes will be saved to the database.

Parameters:

item - The item to be reattached

Throws:

PermissionDeniedException - If the logged in user doesn't have read permission

BaseException - If there is another error

ItemNotFoundException

See Also:

detachItem(BasicItem)

initCollection

public void initCollection(BasicItem item,
                           String collectionName)
                    throws BaseException

Initialise a collection on an item. This method is useful if you detach an item but needs to use a collection while it is detached. Since collections are not loaded until they are needed, you will get an exception if you try to access an unitialised collection of a detached item. One example is if you have detach a Quota object and calls the Quota.getQuotaValue(QuotaType, Location) method.

Parameters:

item - The item

collectionName - The name of the collection

Throws:

BaseException - If there is an error

See Also:

detachItem(BasicItem), reattachItem(BasicItem)

finalize

protected void finalize()
                 throws Throwable

Clean up if a bad client application forgot to close the connection.

Overrides:

finalize in class Object

Throws:

Throwable