A (very) high-level view of the Hibernate architecture
SessionFactory (org.hibernate.SessionFactory): A threadsafe, immutable cache of compiled mappings for a single database. A factory for Session and a client of ConnectionProvider, SessionFactory can hold an optional (second-level) cache of data that is reusable between transactions at a process, or cluster, level.
| Method Summary |
| Session getCurrentSession() |
Obtains the current session. |
| Statistics getStatistics() |
Retrieve the statistics fopr this factory. |
| Session openSession() |
Open a Session. |
| StatelessSession openStatelessSession() |
Open a new stateless session. |
Session (org.hibernate.Session): A single-threaded, short-lived object representing a conversation between the application and the persistent store. It wraps a JDBC connection and is a factory for Transaction. Session holds a mandatory first-level cache of persistent objects that are used when navigating the object graph or looking up objects by identifier.
The main function of the Session is to offer create, read and delete operations for instances of mapped entity classes.
| Method Summary |
| Transaction |
beginTransaction() |
Begin a unit of work and return the associated Transaction object. |
| void |
cancelQuery() |
Cancel the execution of the current query. |
| void |
clear() |
Completely clear the session. |
| Connection |
close() |
End the session by releasing the JDBC connection and cleaning up. |
| Query |
createQuery(String queryString) |
Create a new instance of Query for the given HQL query string. |
| SQLQuery |
createSQLQuery(String queryString) |
Create a new instance of SQLQuery for the given SQL query string. |
| void |
delete(Object object) |
Remove a persistent instance from the datastore. |
| boolean |
isConnected() |
Check if the session is currently connected. |
| Object |
load(Class theClass,Serializable id) |
Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists. |
| Object |
merge(Object object) |
Copy the state of the given object onto the persistent object with the same identifier. |
| void |
persist(Object object) |
Make a transient instance persistent. |
| void |
refresh(Object object) |
Re-read the state of the given instance from the underlying database. |
| Serializable |
save(Object object) |
Persist the given transient instance, first assigning a generated identifier. |
| void |
saveOrUpdate(Object object) |
Either save(Object) or update(Object) the given instance, depending upon resolution of the unsaved-value checks (see the manual for discussion of unsaved-value checking). |
| void |
update(Object object) |
Update the persistent instance with the identifier of the given detached instance. |
Configuration Class: Represents configuration file of the application.
-
An instance of Configuration allows the application to specify properties and mapping documents to be used when creating a SessionFactory.
-
Usually an application will create a single Configuration, build a single instance of SessionFactory and then instantiate Sessions in threads servicing client requests.
-
The Configuration is meant only as an initialization-time object.
-
SessionFactorys are immutable and do not retain any association back to the Configuration.
-
A new Configuration will use the properties specified in hibernate.properties by default.
| Method Summary |
| Configuration |
addClass(Class persistentClass) |
Read a mapping as an application resource using the convention that a class named foo.bar.Foo is mapped by a file foo/bar/Foo.hbm.xml which can be resolved as a classpath resource. |
| Configuration |
addDirectory(File dir) |
Read all mapping documents from a directory tree. |
| Configuration |
addFile(File xmlFile) |
Read mappings from a particular XML file |
| Configuration |
addJar(File jar) |
Read all mappings from a jar file Assumes that any file named *.hbm.xml is a mapping document. |
| SessionFactory |
buildSessionFactory() |
Create a SessionFactory using the properties and mappings in this configuration. |
| Configuration |
configure() |
Use the mappings and properties specified in an application resource named hibernate.cfg.xml. |
| Configuration |
configure(File configFile) |
Use the mappings and properties specified in the given application file. |
Transaction (org.hibernate.Transaction)(Optional)
- A single-threaded, short-lived object used by the application to specify atomic units of work.
-
It abstracts the application from the underlying JDBC, JTA or CORBA transaction.
-
A Session might span several Transactions in some cases.
-
However, transaction demarcation, either using the underlying API or Transaction, is never optional.
ConnectionProvider (org.hibernate.connection.ConnectionProvider)(Optional)
- A factory for, and pool of, JDBC connections.
-
It abstracts the application from underlying Datasource or DriverManager.
-
It is not exposed to application, but it can be extended and/or implemented by the developer.
| Transaction Method Summary |
| void |
begin() |
Begin a new transaction. |
| void |
commit() |
Flush the associated Session and end the unit of work (unless we are in FlushMode.MANUAL. |
| void |
rollback() |
Force the underlying transaction to roll back. |
| void |
setTimeout(int seconds) |
Set the transaction timeout for any transaction started by a subsequent call to begin() on this instance. |
| boolean |
isActive() |
Is this transaction still active? Again, this only returns information in relation to the local transaction, not the actual underlying transaction |
TransactionFactory (org.hibernate.TransactionFactory)(Optional)
- A factory for Transaction instances.
-
It is not exposed to the application, but it can be extended and/or implemented by the developer.
-
Extension InterfacesHibernate offers a range of optional extension interfaces you can implement to customize the behavior of your persistence layer.
-
Given a “minimal” architecture, the application bypasses the Transaction/TransactionFactory and/or ConnectionProvider APIs to communicate with JTA or JDBC directly.
org.hibernate.Query Interface
- An object-oriented representation of a Hibernate query.
-
A Query instance is obtained by calling Session.createQuery().
-
This interface exposes some extra functionality beyond that provided by Session.iterate() and Session.find():
-
A particular page of the result set may be selected by calling setMaxResults(), setFirstResult()
-
Named query parameters may be used
-
The results may be returned as an instance of ScrollableResults
| Method Summary |
| int |
executeUpdate() |
Execute the update or delete statement. |
| Iterator |
iterate() |
Return the query results as an Iterator. |
| List |
list() |
Return the query results as a List. |
| ScrollableResults |
scroll() |
Return the query results as ScrollableResults. |
JMX Integration
- JMX is the J2EE standard for the management of Java components.
-
Hibernate can be managed via a JMX standard service.
-
AN MBean implementation is provided in the distribution: org.hibernate.jmx.HibernateService.
-
For an example of how to deploy Hibernate as a JMX service on the JBoss Application Server, please see the JBoss User Guide. JBoss AS also provides these benefits if you deploy using JMX:
Session Management
- The Hibernate Session’s life cycle can be automatically bound to the scope of a JTA transaction.
-
This means that you no longer have to manually open and close the Session; this becomes the job of a JBoss EJB interceptor.
-
You also do not have to worry about transaction demarcation in your code (if you would like to write a portable persistence layer use the optional Hibernate Transaction API for this).
-
You call the HibernateContext to access a Session.
HAR deployment
- The Hibernate JMX service is deployed using a JBoss service deployment descriptor in an EAR and/or SAR file, as it supports all the usual configuration options of a Hibernate SessionFactory.
-
However, you still need to name all your mapping files in the deployment descriptor.
-
If you use the optional HAR deployment, JBoss will automatically detect all mapping files in your HAR file.
Recent Comments