session_api.pot

hibernate-distribution-3.3.1.GA-dist.zip源码

# SOME DESCRIPTIVE TITLE.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: http://bugs.kde.org\n"
"POT-Creation-Date: 2008-08-14 15:28+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <[e-mail]>\n"
"MIME-Version: 1.0\n"
"Content-Type: application/x-xml2pot; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. Tag: title
#: session_api.xml:29
#, no-c-format
msgid "Working with objects"
msgstr ""

#. Tag: para
#: session_api.xml:31
#, no-c-format
msgid "Hibernate is a full object/relational mapping solution that not only shields the developer from the details of the underlying database management system, but also offers <emphasis>state management</emphasis> of objects. This is, contrary to the management of SQL <literal>statements</literal> in common JDBC/SQL persistence layers, a very natural object-oriented view of persistence in Java applications."
msgstr ""

#. Tag: para
#: session_api.xml:40
#, no-c-format
msgid "In other words, Hibernate application developers should always think about the <emphasis>state</emphasis> of their objects, and not necessarily about the execution of SQL statements. This part is taken care of by Hibernate and is only relevant for the application developer when tuning the performance of the system."
msgstr ""

#. Tag: title
#: session_api.xml:48
#, no-c-format
msgid "Hibernate object states"
msgstr ""

#. Tag: para
#: session_api.xml:50
#, no-c-format
msgid "Hibernate defines and supports the following object states:"
msgstr ""

#. Tag: para
#: session_api.xml:56
#, no-c-format
msgid "<emphasis>Transient</emphasis> - an object is transient if it has just been instantiated using the <literal>new</literal> operator, and it is not associated with a Hibernate <literal>Session</literal>. It has no persistent representation in the database and no identifier value has been assigned. Transient instances will be destroyed by the garbage collector if the application doesn't hold a reference anymore. Use the Hibernate <literal>Session</literal> to make an object persistent (and let Hibernate take care of the SQL statements that need to be executed for this transition)."
msgstr ""

#. Tag: para
#: session_api.xml:68
#, no-c-format
msgid "<emphasis>Persistent</emphasis> - a persistent instance has a representation in the database and an identifier value. It might just have been saved or loaded, however, it is by definition in the scope of a <literal>Session</literal>. Hibernate will detect any changes made to an object in persistent state and synchronize the state with the database when the unit of work completes. Developers don't execute manual <literal>UPDATE</literal> statements, or <literal>DELETE</literal> statements when an object should be made transient."
msgstr ""

#. Tag: para
#: session_api.xml:79
#, no-c-format
msgid "<emphasis>Detached</emphasis> - a detached instance is an object that has been persistent, but its <literal>Session</literal> has been closed. The reference to the object is still valid, of course, and the detached instance might even be modified in this state. A detached instance can be reattached to a new <literal>Session</literal> at a later point in time, making it (and all the modifications) persistent again. This feature enables a programming model for long running units of work that require user think-time. We call them <emphasis>application transactions</emphasis>, i.e. a unit of work from the point of view of the user."
msgstr ""

#. Tag: para
#: session_api.xml:93
#, no-c-format
msgid "We'll now discuss the states and state transitions (and the Hibernate methods that trigger a transition) in more detail."
msgstr ""

#. Tag: title
#: session_api.xml:101
#, no-c-format
msgid "Making objects persistent"
msgstr ""

#. Tag: para
#: session_api.xml:103
#, no-c-format
msgid "Newly instantiated instances of a a persistent class are considered <emphasis>transient</emphasis> by Hibernate. We can make a transient instance <emphasis>persistent</emphasis> by associating it with a session:"
msgstr ""

#. Tag: programlisting
#: session_api.xml:110
#, no-c-format
msgid ""
      "<![CDATA[DomesticCat fritz = new DomesticCat();\n"
      "fritz.setColor(Color.GINGER);\n"
      "fritz.setSex('M');\n"
      "fritz.setName(\"Fritz\");\n"
      "Long generatedId = (Long) sess.save(fritz);]]>"
msgstr ""

#. Tag: para
#: session_api.xml:112
#, no-c-format
msgid "If <literal>Cat</literal> has a generated identifier, the identifier is generated and assigned to the <literal>cat</literal> when <literal>save()</literal> is called. If <literal>Cat</literal> has an <literal>assigned</literal> identifier, or a composite key, the identifier should be assigned to the <literal>cat</literal> instance before calling <literal>save()</literal>. You may also use <literal>persist()</literal> instead of <literal>save()</literal>, with the semantics defined in the EJB3 early draft."
msgstr ""

#. Tag: para
#: session_api.xml:124
#, no-c-format
msgid "<literal>persist()</literal> makes a transient instance persistent. However, it doesn't guarantee that the identifier value will be assigned to the persistent instance immediately, the assignment might happen at flush time. <literal>persist()</literal> also guarantees that it will not execute an <literal>INSERT</literal> statement if it is called outside of transaction boundaries. This is useful in long-running conversations with an extended Session/persistence context."
msgstr ""

#. Tag: para
#: session_api.xml:135
#, no-c-format
msgid "<literal>save()</literal> does guarantee to return an identifier. If an INSERT has to be executed to get the identifier ( e.g. \"identity\" generator, not \"sequence\"), this INSERT happens immediately, no matter if you are inside or outside of a transaction. This is problematic in a long-running conversation with an extended Session/persistence context."
msgstr ""

#. Tag: para
#: session_api.xml:145
#, no-c-format
msgid "Alternatively, you may assign the identifier using an overloaded version of <literal>save()</literal>."
msgstr ""

#. Tag: programlisting
#: session_api.xml:150
#, no-c-format
msgid ""
      "<![CDATA[DomesticCat pk = new DomesticCat();\n"
      "pk.setColor(Color.TABBY);\n"
      "pk.setSex('F');\n"
      "pk.setName(\"PK\");\n"
      "pk.setKittens( new HashSet() );\n"
      "pk.addKitten(fritz);\n"
      "sess.save( pk, new Long(1234) );]]>"
msgstr ""

#. Tag: para
#: session_api.xml:152
#, no-c-format
msgid "If the object you make persistent has associated objects (e.g. the <literal>kittens</literal> collection in the previous example), these objects may be made persistent in any order you like unless you have a <literal>NOT NULL</literal> constraint upon a foreign key column. There is never a risk of violating foreign key constraints. However, you might violate a <literal>NOT NULL</literal> constraint if you <literal>save()</literal> the objects in the wrong order."
msgstr ""

#. Tag: para
#: session_api.xml:162
#, no-c-format
msgid "Usually you don't bother with this detail, as you'll very likely use Hibernate's <emphasis>transitive persistence</emphasis> feature to save the associated objects automatically. Then, even <literal>NOT NULL</literal> constraint violations don't occur - Hibernate will take care of everything. Transitive persistence is discussed later in this chapter."
msgstr ""

#. Tag: title
#: session_api.xml:173
#, no-c-format
msgid "Loading an object"
msgstr ""

#. Tag: para
#: session_api.xml:175
#, no-c-format
msgid "The <literal>load()</literal> methods of <literal>Session</literal> gives you a way to retrieve a persistent instance if you already know its identifier. <literal>load()</literal> takes a class object and will load the state into a newly instantiated instance of that class, in persistent state."
msgstr ""

#. Tag: programlisting
#: session_api.xml:182
#, no-c-format
msgid "<![CDATA[Cat fritz = (Cat) sess.load(Cat.class, generatedId);]]>"
msgstr ""

#. Tag: programlisting
#: session_api.xml:184
#, no-c-format
msgid ""
      "<![CDATA[// you need to wrap primitive identifiers\n"
      "long id = 1234;\n"
      "DomesticCat pk = (DomesticCat) sess.load( DomesticCat.class, new Long(id) );]]>"
msgstr ""

#. Tag: para
#: session_api.xml:186
#, no-c-format
msgid "Alternatively, you can load state into a given instance:"
msgstr ""

#. Tag: programlisting
#: session_api.xml:190
#, no-c-format
msgid ""
      "<![CDATA[Cat cat = new DomesticCat();\n"
      "// load pk's state into cat\n"
      "sess.load( cat, new Long(pkId) );\n"
      "Set kittens = cat.getKittens();]]>"
msgstr ""

#. Tag: para
#: session_api.xml:192
#, no-c-format
msgid "Note that <literal>load()</literal> will throw an unrecoverable exception if there is no matching database row. If the class is mapped with a proxy, <literal>load()</literal> just returns an uninitialized proxy and does not actually hit the database until you invoke a method of the proxy. This behaviour is very useful if you wish to create an association to an object without actually loading it from the database. It also allows multiple instances to be loaded as a batch if <literal>batch-size</literal> is defined for the class mapping."
msgstr ""

#. Tag: para
#: session_api.xml:203
#, no-c-format
msgid "If you are not certain that a matching row exists, you should use the <literal>get()</literal> method, which hits the database immediately and returns null if there is no matching row."
msgstr ""

#. Tag: programlisting
#: session_api.xml:209
#, no-c-format
msgid ""
      "<![CDATA[Cat cat = (Cat) sess.get(Cat.class, id);\n"
      "if (cat==null) {\n"
      "    cat = new Cat();\n"
      "    sess.save(cat, id);\n"
      "}\n"
      "return cat;]]>"
msgstr ""

#. Tag: para
#: session_api.xml:211
#, no-c-format
msgid "You may even load an object using an SQL <literal>SELECT ... FOR UPDATE</literal>, using a <literal>LockMode</literal>. See the API documentation for more information."
msgstr ""

#. Tag: programlisting
#: session_api.xml:216
#, no-c-format
msgid "<![CDATA[Cat cat = (Cat) sess.get(Cat.class, id, LockMode.UPGRADE);]]>"
msgstr ""

#. Tag: para
#: session_api.xml:218
#, no-c-format
msgid "Note that any associated instances or contained collections are <emphasis>not</emphasis> selected <literal>FOR UPDATE</literal>, unless you decide to specify <literal>lock</literal> or <literal>all</literal> as a cascade style for the association."
msgstr ""

#. Tag: para
#: session_api.xml:225
#, no-c-format
msgid "It is possible to re-load an object and all its collections at any time, using the <literal>refresh()</literal> method. This is useful when database triggers are used to initialize some of the properties of the object."
msgstr ""

#. Tag: programlisting
#: session_api.xml:231
#, no-c-format
msgid ""
      "<![CDATA[sess.save(cat);\n"
      "sess.flush(); //force the SQL INSERT\n"
      "sess.refresh(cat); //re-read the state (after the trigger executes)]]>"
msgstr ""

#. Tag: para
#: session_api.xml:233
#, no-c-format
msgid "An important question usually appears at this point: How much does Hibernate load from the database and how many SQL <literal>SELECT</literal>s will it use? This depends on the <emphasis>fetching strategy</emphasis> and is explained in <xref linkend=\"performance-fetching\"/>."
msgstr ""

#. Tag: title
#: session_api.xml:243
#, no-c-format
msgid "Querying"
msgstr ""

#. Tag: para
#: session_api.xml:245
#, no-c-format
msgid "If you don't know the identifiers of the objects you are looking for, you need a query. Hibernate supports an easy-to-use but powerful object oriented query language (HQL). For programmatic query creation, Hibernate supports a sophisticated Criteria and Example query feature (QBC and QBE). You may also express your query in the native SQL of your database, with optional support from Hibernate for result set conversion into objects."
msgstr ""

#. Tag: title
#: session_api.xml:255
#, no-c-format
msgid "Executing queries"
msgstr ""

#. Tag: para
#: session_api.xml:257
#, no-c-format
msgid "HQL and native SQL queries are represented with an instance of <literal>org.hibernate.Query</literal>. This interface offers methods for parameter binding, result set handling, and for the execution of the actual query. You always obtain a <literal>Query</literal> using the current <literal>Session</literal>:"
msgstr ""

#. Tag: programlisting
#: session_api.xml:264
#, no-c-format
msgid ""
      "<![CDATA[List cats = session.createQuery(\n"
      "    \"from Cat as cat where cat.birthdate < ?\")\n"
      "    .setDate(0, date)\n"
      "    .list();\n"
      "\n"
      "List mothers = session.createQuery(\n"
      "    \"select mother from Cat as cat join cat.mother as mother where cat.name = ?\")\n"
      "    .setString(0, name)\n"
      "    .list();\n"
      "\n"
      "List kittens = session.createQuery(\n"
      "    \"from Cat as cat where cat.mother = ?\")\n"
      "    .setEntity(0, pk)\n"
      "    .list();\n"
      "\n"
      "Cat mother = (Cat) session.createQuery(\n"
      "    \"select cat.mother from Cat as cat where cat = ?\")\n"
      "    .setEntity(0, izi)\n"
      "    .uniqueResult();]]\n"
      "\n"
      "Query mothersWithKittens = (Cat) session.createQuery(\n"
      "    \"select mother from Cat as mother left join fetch mother.kittens\");\n"
      "Set uniqueMothers = new HashSet(mothersWithKittens.list());]]>"
msgstr ""

#. Tag: para
#: session_api.xml:266
#, no-c-format
msgid "A query is usually executed by invoking <literal>list()</literal>, the result of the query will be loaded completely into a collection in memory. Entity instances retrieved by a query are in persistent state. The <literal>uniqueResult()</literal> method offers a shortcut if you know your query will only return a single object. Note that queries that make use of eager fetching of collections usually return duplicates of the root objects (but with their collections initialized). You can filter these duplicates simply through a <literal>Set</literal>."
msgstr ""

#. Tag: title
#: session_api.xml:278
#, no-c-format
msgid "Iterating results"
msgstr ""

#. Tag: para
#: session_api.xml:280
#, no-c-format
msgid "Occasionally, you might be able to achieve better performance by executing the query using the <literal>iterate()</literal> method. This will only usually be the case if you expect that the actual entity instances returned by the query will already be in the session or second-level cache. If they are not already cached, <literal>iterate()</literal> will be slower than <literal>list()</literal> and might require many database hits for a simple query, usually <emphasis>1</emphasis> for the initial select which only returns identifiers, and <emphasis>n</emphasis> additional selects to initialize the actual instances."
msgstr ""

#. Tag: programlisting
#: session_api.xml:292
#, no-c-format
msgid ""
      "<![CDATA[// fetch ids\n"
      "Iterator iter = sess.createQuery(\"from eg.Qux q order by q.likeliness\").iterate();\n"
      "while ( iter.hasNext() ) {\n"
      "    Qux qux = (Qux) iter.next();  // fetch the object\n"
      "    // something we couldnt express in the query\n"
      "    if ( qux.calculateComplicatedAlgorithm() ) {\n"
      "        // delete the current instance\n"
      "        iter.remove();\n"
      "        // dont need to process the rest\n"
      "        break;\n"
      "    }\n"
      "}]]>"
msgstr ""

#. Tag: title
#: session_api.xml:296