de.nava.informa.impl.hibernate
Class ChannelBuilder

java.lang.Object
  de.nava.informa.impl.hibernate.ChannelBuilder

All Implemented Interfaces:

ChannelBuilderIF

public class ChannelBuilder
extends Object
implements ChannelBuilderIF

Factory for the creation of the channel object model with the hibernate persistent store.

NOT THREAD SAFE

Hibernate Multi-threading notes: ChannelBuilder has some subtleties as it relates to threading. The specifics of the way it is supported still need to be proven. Certainly the error handling here and in UpdateChannelTask and in ChannelRegistry is incomplete. It seems to work, but I would consider it incomplete still.

The key facts are (1) Sessions are not thread safe and (2) Sessions should have relatively short lifespans.

To support this, there is a mode of using ChannelBuilder where it holds on to a SessionHandler and manages the creation and destruction of Sessions on behalf of the caller. When you supply a SessionHandler to ChannelBuilder, you may use the beginTransaction() and endTransaction() calls to take all the steps needed before and after a transaction. At the end of endTransaction() the transaction will be closed and the session will be flushed and closed. To use this mode, you should (1) Create a SessionHandler , (2) Create a JDBC Connection to the database, (3) sessionHandler.setConnection(connection), and (4) use new ChannelBuilder(sessionHandler).

Author:

Niko Schmuck (niko@nava.de)

Constructor Summary

ChannelBuilder(Session session)
ChannelBuilder constructor.

ChannelBuilder(SessionHandler handler)
ChannelBuilder constructor.

Method Summary

void	beginTransaction() Processing needed at the start of a transaction.
void	close() Closes the builder.
CategoryIF	createCategory(CategoryIF parent, String title)
CategoryIF	createCategory(CategoryIF parent, String title, String domain)
ChannelIF	createChannel(org.jdom.Element channelElement, String title)
ChannelIF	createChannel(org.jdom.Element channelElement, String title, String location) May throw runtime HibernateException
ChannelIF	createChannel(String title)
ChannelIF	createChannel(String title, String location)
ChannelGroupIF	createChannelGroup(String title)
CloudIF	createCloud(String domain, int port, String path, String registerProcedure, String protocol)
ImageIF	createImage(String title, URL location, URL link)
ItemIF	createItem(ChannelIF channel, ItemIF item)
ItemIF	createItem(ChannelIF channel, String title, String description, URL link) Creates a news item and assign it to the given channel.
ItemIF	createItem(org.jdom.Element itemElement, ChannelIF channel, String title, String description, URL link)
ItemEnclosureIF	createItemEnclosure(ItemIF item, URL location, String type, int length)
ItemGuidIF	createItemGuid(ItemIF item, String location, boolean permaLink)
ItemSourceIF	createItemSource(ItemIF item, String name, String location, Date timestamp)
ItemSourceIF	createItemSource(String name, String location, Date timestamp)
TextInputIF	createTextInput(String title, String description, String name, URL link)
void	delete(Object o) Hibernate Delete some object
void	endTransaction() Processing needed at the end of a transaction.
Session	getSession() Certain Hibernate calls require the session.
void	init(Properties props) Sets the runtime properties defined for this channel builder.
boolean	inTransaction() Check if we are already in the middle of a transaction.
Channel	reload(Channel channel) Reloads channel for use in new session.
ChannelGroup	reload(ChannelGroup group) Reloads group for use in new session.
Item	reload(Item item) Reloads item for use in new session.
void	resetTransaction() resetTransaction - Used during error handling.
protected void	save(Object dataObject)
void	update(Object o) update - Hibernate Update some object

Methods inherited from class java.lang.Object

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

Constructor Detail

ChannelBuilder

public ChannelBuilder(Session session)

ChannelBuilder constructor. Caller is responsible for managing sessions and transactions.

ChannelBuilder

public ChannelBuilder(SessionHandler handler)

ChannelBuilder constructor. ChannelBuilder will manage sessions and transactions. Supplied SessionHandler needs to have a live JDBC connection available.

Method Detail

beginTransaction

public void beginTransaction()
                      throws ChannelBuilderException

Processing needed at the start of a transaction. - creating a session - beginning the transaction

Specified by:

beginTransaction in interface ChannelBuilderIF

Throws:

ChannelBuilderException

endTransaction

public void endTransaction()
                    throws ChannelBuilderException

Processing needed at the end of a transaction. - commit the transaction - flush the session - close the session TODO: catch the exception so this method doesn't have any throws.

Specified by:

endTransaction in interface ChannelBuilderIF

Throws:

ChannelBuilderException

inTransaction

public boolean inTransaction()

Check if we are already in the middle of a transaction. This is needed because as of now begin/endTransactions cannot be nested and in fact give assert errors if you try.

Returns:

- boolean indicating whether we are currently in a transaction.

resetTransaction

public void resetTransaction()

resetTransaction - Used during error handling. If in a catch block there is a potentially still open transaction (i.e. beginTransaction() was called) then call this method to reset the state of the ChannelBuilder and clean up the transaction.

getSession

public Session getSession()

Certain Hibernate calls require the session. Note that this call should only be made between a beginTransaction and endTransaction call which is why we throw an IllegalStateException otherwise.

update

public void update(Object o)
            throws ChannelBuilderException

update - Hibernate Update some object

Specified by:

update in interface ChannelBuilderIF

Parameters:

o -

Throws:

ChannelBuilderException - -

delete

public void delete(Object o)
            throws ChannelBuilderException

Hibernate Delete some object

Parameters:

o - - Object to Delete

Throws:

ChannelBuilderException - - Translation of Hibernate exception

init

public void init(Properties props)
          throws ChannelBuilderException

Description copied from interface: ChannelBuilderIF

Sets the runtime properties defined for this channel builder. This method will be invoked by the ChannelBuilderFactory when the ChannelBuilder is first created.

Specified by:

init in interface ChannelBuilderIF

Parameters:

props - The parsed set of properties which may be applied to this object.

Throws:

ChannelBuilderException - If the initialisation fails for some reason.

createChannelGroup

public ChannelGroupIF createChannelGroup(String title)

Specified by:

createChannelGroup in interface ChannelBuilderIF

createChannel

public ChannelIF createChannel(String title)

Specified by:

createChannel in interface ChannelBuilderIF

createChannel

public ChannelIF createChannel(org.jdom.Element channelElement,
                               String title)

Specified by:

createChannel in interface ChannelBuilderIF

createChannel

public ChannelIF createChannel(String title,
                               String location)

Specified by:

createChannel in interface ChannelBuilderIF

createChannel

public ChannelIF createChannel(org.jdom.Element channelElement,
                               String title,
                               String location)

May throw runtime HibernateException

Specified by:

createChannel in interface ChannelBuilderIF

createItem

public ItemIF createItem(ChannelIF channel,
                         String title,
                         String description,
                         URL link)

Description copied from interface: ChannelBuilderIF

Creates a news item and assign it to the given channel.

Specified by:

createItem in interface ChannelBuilderIF

createItem

public ItemIF createItem(org.jdom.Element itemElement,
                         ChannelIF channel,
                         String title,
                         String description,
                         URL link)

Specified by:

createItem in interface ChannelBuilderIF

createItem

public ItemIF createItem(ChannelIF channel,
                         ItemIF item)

Specified by:

createItem in interface ChannelBuilderIF

createImage

public ImageIF createImage(String title,
                           URL location,
                           URL link)

Specified by:

createImage in interface ChannelBuilderIF

createCloud

public CloudIF createCloud(String domain,
                           int port,
                           String path,
                           String registerProcedure,
                           String protocol)

Specified by:

createCloud in interface ChannelBuilderIF

createTextInput

public TextInputIF createTextInput(String title,
                                   String description,
                                   String name,
                                   URL link)

Specified by:

createTextInput in interface ChannelBuilderIF

createItemSource

public ItemSourceIF createItemSource(ItemIF item,
                                     String name,
                                     String location,
                                     Date timestamp)

Specified by:

createItemSource in interface ChannelBuilderIF

createItemSource

public ItemSourceIF createItemSource(String name,
                                     String location,
                                     Date timestamp)

createItemEnclosure

public ItemEnclosureIF createItemEnclosure(ItemIF item,
                                           URL location,
                                           String type,
                                           int length)

Specified by:

createItemEnclosure in interface ChannelBuilderIF

createItemGuid

public ItemGuidIF createItemGuid(ItemIF item,
                                 String location,
                                 boolean permaLink)

Specified by:

createItemGuid in interface ChannelBuilderIF

createCategory

public CategoryIF createCategory(CategoryIF parent,
                                 String title)

Specified by:

createCategory in interface ChannelBuilderIF

createCategory

public CategoryIF createCategory(CategoryIF parent,
                                 String title,
                                 String domain)

close

public void close()
           throws ChannelBuilderException

Description copied from interface: ChannelBuilderIF

Closes the builder. After this call, all references to any channel objects provided by this ChannelBuilder are invalidated. If the ChannelBuilder has a connection to a persistant store such as a database, connections may be closed.

Specified by:

close in interface ChannelBuilderIF

Throws:

ChannelBuilderException

reload

public ChannelGroup reload(ChannelGroup group)
                    throws ChannelBuilderException

Reloads group for use in new session.

Parameters:

group - to reload.

Returns:

reloaded group for chaning.

Throws:

ChannelBuilderException - when unable to reload data.

reload

public Channel reload(Channel channel)
               throws ChannelBuilderException

Reloads channel for use in new session.

Parameters:

channel - channel to reload.

Returns:

reloaded channel for chaining.

Throws:

ChannelBuilderException - when unable to reload data.

reload

public Item reload(Item item)
            throws ChannelBuilderException

Reloads item for use in new session.

Parameters:

item - item to reload.

Returns:

reloaded item for chaning.

Throws:

ChannelBuilderException - when unable to reload data.

save

protected void save(Object dataObject)