Menu
▾
▴
[Nhibernate-commit] SF.net SVN: nhibernate:[5394] trunk/nhibernate/src/NHibernate
|
From: <jul...@us...> - 2011-02-24 10:05:43
|
Revision: 5394
http://nhibernate.svn.sourceforge.net/nhibernate/?rev=5394&view=rev
Author: julian-maughan
Date: 2011-02-24 10:05:36 +0000 (Thu, 24 Feb 2011)
Log Message:
-----------
Minor XML documentation refinements
Modified Paths:
--------------
trunk/nhibernate/src/NHibernate/ICriteria.cs
trunk/nhibernate/src/NHibernate/IQuery.cs
trunk/nhibernate/src/NHibernate/ISession.cs
Modified: trunk/nhibernate/src/NHibernate/ICriteria.cs
===================================================================
--- trunk/nhibernate/src/NHibernate/ICriteria.cs 2011-02-23 09:44:22 UTC (rev 5393)
+++ trunk/nhibernate/src/NHibernate/ICriteria.cs 2011-02-24 10:05:36 UTC (rev 5394)
@@ -17,38 +17,39 @@
/// where there is a variable number of conditions to be placed upon the result set.
/// </para>
/// <para>
- /// The Session is a factory for ICriteria. Expression instances are usually obtained via
+ /// The Session is a factory for ICriteria. Expression instances are usually obtained via
/// the factory methods on <see cref="Expression" />. eg:
/// </para>
/// <code>
- /// IList cats = session.CreateCriteria(typeof(Cat))
- /// .Add( Expression.Like("name", "Iz%") )
- /// .Add( Expression.Gt( "weight", minWeight ) )
- /// .AddOrder( Order.Asc("age") )
- /// .List();
+ /// IList cats = session.CreateCriteria(typeof(Cat))
+ /// .Add(Expression.Like("name", "Iz%"))
+ /// .Add(Expression.Gt("weight", minWeight))
+ /// .AddOrder(Order.Asc("age"))
+ /// .List();
/// </code>
- /// You may navigate associations using <see cref="CreateAlias(string,string)" /> or <see cref="CreateCriteria(string)" />.
+ /// You may navigate associations using <see cref="CreateAlias(string, string)" />
+ /// or <see cref="CreateCriteria(string)" />. eg:
/// <code>
- /// IList cats = session.CreateCriteria(typeof(Cat))
- /// .CreateCriteria("kittens")
- /// .Add( Expression.like("name", "Iz%") )
- /// .List();
- /// </code>
+ /// IList<Cat> cats = session.CreateCriteria<Cat>
+ /// .CreateCriteria("kittens")
+ /// .Add(Expression.like("name", "Iz%"))
+ /// .List<Cat>();
+ /// </code>
/// <para>
- /// You may specify projection and aggregation using <tt>Projection</tt>
- /// instances obtained via the factory methods on <tt>Projections</tt>.
+ /// You may specify projection and aggregation using <c>Projection</c> instances obtained
+ /// via the factory methods on <c>Projections</c>. eg:
/// <code>
- /// IList cats = session.CreateCriteria(typeof(Cat))
- /// .setProjection( Projections.ProjectionList()
- /// .Add( Projections.RowCount() )
- /// .Add( Projections.Avg("weight") )
- /// .Add( Projections.Max("weight") )
- /// .Add( Projections.Min("weight") )
- /// .Add( Projections.GroupProperty("color") )
- /// )
- /// .AddOrder( Order.Asc("color") )
- /// .List();
- /// </code>
+ /// IList<Cat> cats = session.CreateCriteria<Cat>
+ /// .SetProjection(
+ /// Projections.ProjectionList()
+ /// .Add(Projections.RowCount())
+ /// .Add(Projections.Avg("weight"))
+ /// .Add(Projections.Max("weight"))
+ /// .Add(Projections.Min("weight"))
+ /// .Add(Projections.GroupProperty("color")))
+ /// .AddOrder(Order.Asc("color"))
+ /// .List<Cat>();
+ /// </code>
/// </para>
/// </remarks>
public interface ICriteria : ICloneable
@@ -82,7 +83,7 @@
ICriteria Add(ICriterion expression);
/// <summary>
- /// An an Order to the result set
+ /// An an Order to the result set
/// </summary>
/// <param name="order"></param>
ICriteria AddOrder(Order order);
@@ -148,7 +149,7 @@
ICriteria CreateCriteria(string associationPath);
/// <summary>
- /// Create a new <see cref="ICriteria" />, "rooted" at the associated entity,
+ /// Create a new <see cref="ICriteria" />, "rooted" at the associated entity,
/// using the specified join type.
/// </summary>
/// <param name="associationPath">A dot-seperated property path</param>
@@ -327,7 +328,7 @@
/// Gets the root entity type if available, throws otherwise
/// </summary>
/// <remarks>
- /// This is an NHibernate specific method, used by several dependent
+ /// This is an NHibernate specific method, used by several dependent
/// frameworks for advance integration with NHibernate.
/// </remarks>
System.Type GetRootEntityTypeIfAvailable();
Modified: trunk/nhibernate/src/NHibernate/IQuery.cs
===================================================================
--- trunk/nhibernate/src/NHibernate/IQuery.cs 2011-02-23 09:44:22 UTC (rev 5393)
+++ trunk/nhibernate/src/NHibernate/IQuery.cs 2011-02-24 10:05:36 UTC (rev 5394)
@@ -10,39 +10,43 @@
/// An object-oriented representation of a NHibernate query.
/// </summary>
/// <remarks>
- /// An <c>IQuery</c> instance is obtained by calling <c>ISession.CreateQuery()</c>. This interface
- /// exposes some extra functionality beyond that provided by <c>ISession.Iterate()</c> and
- /// <c>ISession.List()</c>;
- /// <list>
+ /// An <c>IQuery</c> instance is obtained by calling <see cref="ISession.CreateQuery(string)" />.
+ /// Key features of this interface include:
+ /// <list type="bullet">
/// <item>
- /// A particular page of the result set may be selected by calling
- /// <c>SetMaxResults()</c>, <c>SetFirstResult()</c>. The generated sql
+ /// Paging: A particular page of the result set may be selected by calling
+ /// <see cref="SetMaxResults(int)" />, <see cref="SetFirstResult(int)" />. The generated SQL
/// depends on the capabilities of the <see cref="Dialect.Dialect"/>. Some
/// Dialects are for databases that have built in paging (LIMIT) and those capabilities
- /// will be used to limit the number of records returned by the sql statement.
+ /// will be used to limit the number of records returned by the SQL statement.
/// If the database does not support LIMITs then all of the records will be returned,
/// but the objects created will be limited to the specific results requested.
/// </item>
- /// <item>Named query parameters may be used</item>
+ /// <item>
+ /// Named parameters
+ /// </item>
+ /// <item>
+ /// Ability to return 'read-only' entities
+ /// </item>
/// </list>
/// <para>
- /// Named query parameters are tokens of the form <c>:name</c> in the query string. A value is bound
- /// to the <c>Int32</c> parameter <c>:foo</c> by calling
+ /// Named query parameters are tokens of the form <c>:name</c> in the query string. For example, a
+ /// value is bound to the <c>Int32</c> parameter <c>:foo</c> by calling:
/// <code>
- /// SetParameter("foo", foo, NHibernateUtil.Int32);
+ /// SetParameter("foo", foo, NHibernateUtil.Int32);
/// </code>
- /// for example. A name may appear multiple times in the query string.
+ /// A name may appear multiple times in the query string.
/// </para>
/// <para>
- /// Unnamed parameters <c>?</c> are also supported. To bind a value to an unnamed
- /// parameter use a Set method that accepts an <c>Int32</c> positional argument - numbered from
- /// zero.
+ /// Unnamed parameters <c>?</c> are also supported. To bind a value to an unnamed
+ /// parameter use a Set method that accepts an <c>Int32</c> positional argument - numbered from
+ /// zero.
/// </para>
/// <para>
/// You may not mix and match unnamed parameters and named parameters in the same query.
/// </para>
/// <para>
- /// Queries are executed by calling <c>List()</c> or <c>Iterate()</c>. A query
+ /// Queries are executed by calling <see cref="IQuery.List()" /> or <see cref="IQuery.Enumerable()" />. A query
/// may be re-executed by subsequent invocations. Its lifespan is, however, bounded by the lifespan
/// of the <c>ISession</c> that created it.
/// </para>
Modified: trunk/nhibernate/src/NHibernate/ISession.cs
===================================================================
--- trunk/nhibernate/src/NHibernate/ISession.cs 2011-02-23 09:44:22 UTC (rev 5393)
+++ trunk/nhibernate/src/NHibernate/ISession.cs 2011-02-24 10:05:36 UTC (rev 5394)
@@ -20,16 +20,16 @@
/// <para>
/// The main function of the <c>ISession</c> is to offer create, find and delete operations
/// for instances of mapped entity classes. Instances may exist in one of two states:
- /// <list>
- /// <item>transient: not associated with any <c>ISession</c></item>
- /// <item>persistent: associated with a <c>ISession</c></item>
+ /// <list type="bullet">
+ /// <item>transient: not associated with any <c>ISession</c></item>
+ /// <item>persistent: associated with a <c>ISession</c></item>
/// </list>
/// </para>
/// <para>
- /// Transient instances may be made persistent by calling <c>Save()</c>, <c>Insert()</c>,
- /// or <c>Update()</c>. Persistent instances may be made transient by calling <c>Delete()</c>.
- /// Any instance returned by a <c>List()</c>, <c>Iterate()</c>, <c>Load()</c>, or <c>Create</c>
- /// method is persistent.
+ /// Transient instances may be made persistent by calling <c>Save()</c>, <c>Insert()</c>,
+ /// or <c>Update()</c>. Persistent instances may be made transient by calling <c>Delete()</c>.
+ /// Any instance returned by a <c>List()</c>, <c>Enumerable()</c>, <c>Load()</c>, or <c>Create()</c>
+ /// method is persistent.
/// </para>
/// <para>
/// <c>Save()</c> results in an SQL <c>INSERT</c>, <c>Delete()</c>
@@ -46,26 +46,28 @@
/// </para>
/// <para>
/// A typical transaction should use the following idiom:
- /// <code>
- /// ISession sess = factory.OpenSession();
- /// ITransaction tx;
- /// try {
- /// tx = sess.BeginTransaction();
- /// //do some work
+ /// <code>
+ /// using (ISession session = factory.OpenSession())
+ /// using (ITransaction tx = session.BeginTransaction())
+ /// {
+ /// try
+ /// {
+ /// // do some work
/// ...
/// tx.Commit();
- /// } catch (Exception e) {
+ /// }
+ /// catch (Exception e)
+ /// {
/// if (tx != null) tx.Rollback();
/// throw;
- /// } finally {
- /// sess.Close();
/// }
- /// </code>
+ /// }
+ /// </code>
/// </para>
/// <para>
- /// If the <c>ISession</c> throws an exception, the transaction must be rolled back and the session
- /// discarded. The internal state of the <c>ISession</c> might not be consistent with the database
- /// after the exception occurs.
+ /// If the <c>ISession</c> throws an exception, the transaction must be rolled back and the session
+ /// discarded. The internal state of the <c>ISession</c> might not be consistent with the database
+ /// after the exception occurs.
/// </para>
/// <seealso cref="ISessionFactory"/>
/// </remarks>
@@ -215,9 +217,9 @@
/// <returns>the persistent instance</returns>
object Load(System.Type theType, object id, LockMode lockMode);
- /// <summary>
+ /// <summary>
/// Return the persistent instance of the given entity class with the given identifier,
- /// obtaining the specified lock mode, assuming the instance exists.
+ /// obtaining the specified lock mode, assuming the instance exists.
/// </summary>
/// <param name="entityName">The entity-name of a persistent class</param>
/// <param name="id">a valid identifier of an existing persistent instance of the class </param>
@@ -263,7 +265,7 @@
/// <returns>The persistent instance or proxy</returns>
T Load<T>(object id);
- /// <summary>
+ /// <summary>
/// Return the persistent instance of the given <paramref name="entityName"/> with the given identifier,
/// assuming that the instance exists.
/// </summary>
@@ -278,7 +280,7 @@
object Load(string entityName, object id);
/// <summary>
- /// Read the persistent state associated with the given identifier into the given transient
+ /// Read the persistent state associated with the given identifier into the given transient
/// instance.
/// </summary>
/// <param name="obj">An "empty" instance of the persistent class</param>
@@ -286,17 +288,17 @@
void Load(object obj, object id);
/// <summary>
- /// Persist all reachable transient objects, reusing the current identifier
+ /// Persist all reachable transient objects, reusing the current identifier
/// values. Note that this will not trigger the Interceptor of the Session.
/// </summary>
/// <param name="obj">a detached instance of a persistent class</param>
/// <param name="replicationMode"></param>
void Replicate(object obj, ReplicationMode replicationMode);
- /// <summary>
+ /// <summary>
/// Persist the state of the given detached instance, reusing the current
/// identifier value. This operation cascades to associated instances if
- /// the association is mapped with <tt>cascade="replicate"</tt>.
+ /// the association is mapped with <tt>cascade="replicate"</tt>.
/// </summary>
/// <param name="entityName"></param>
/// <param name="obj">a detached instance of a persistent class </param>
@@ -331,7 +333,7 @@
/// <returns> the generated identifier </returns>
/// <remarks>
/// This operation cascades to associated instances if the
- /// association is mapped with <tt>cascade="save-update"</tt>.
+ /// association is mapped with <tt>cascade="save-update"</tt>.
/// </remarks>
object Save(string entityName, object obj);
@@ -346,7 +348,7 @@
/// <param name="obj">A transient instance containing new or updated state</param>
void SaveOrUpdate(object obj);
- /// <summary>
+ /// <summary>
/// Either <see cref="Save(String,Object)"/> or <see cref="Update(String,Object)"/>
/// the given instance, depending upon resolution of the unsaved-value checks
/// (see the manual for discussion of unsaved-value checking).
@@ -357,7 +359,7 @@
/// <seealso cref="ISession.Update(String,Object)"/>
/// <remarks>
/// This operation cascades to associated instances if the association is mapped
- /// with <tt>cascade="save-update"</tt>.
+ /// with <tt>cascade="save-update"</tt>.
/// </remarks>
void SaveOrUpdate(string entityName, object obj);
@@ -382,20 +384,20 @@
/// <param name="id">Identifier of persistent instance</param>
void Update(object obj, object id);
- /// <summary>
+ /// <summary>
/// Update the persistent instance with the identifier of the given detached
- /// instance.
+ /// instance.
/// </summary>
/// <param name="entityName">The Entity name.</param>
/// <param name="obj">a detached instance containing updated state </param>
/// <remarks>
/// If there is a persistent instance with the same identifier,
/// an exception is thrown. This operation cascades to associated instances
- /// if the association is mapped with <tt>cascade="save-update"</tt>.
+ /// if the association is mapped with <tt>cascade="save-update"</tt>.
/// </remarks>
void Update(string entityName, object obj);
- /// <summary>
+ /// <summary>
/// Copy the state of the given object onto the persistent object with the same
/// identifier. If there is no persistent instance currently associated with
/// the session, it will be loaded. Return the persistent instance. If the
@@ -403,7 +405,7 @@
/// instance. The given instance does not become associated with the session.
/// This operation cascades to associated instances if the association is mapped
/// with <tt>cascade="merge"</tt>.<br/>
- /// The semantics of this method are defined by JSR-220.
+ /// The semantics of this method are defined by JSR-220.
/// </summary>
/// <param name="obj">a detached instance with state to be copied </param>
/// <returns> an updated persistent instance </returns>
@@ -425,10 +427,10 @@
/// <returns></returns>
object Merge(string entityName, object obj);
- /// <summary>
+ /// <summary>
/// Make a transient instance persistent. This operation cascades to associated
/// instances if the association is mapped with <tt>cascade="persist"</tt>.<br/>
- /// The semantics of this method are defined by JSR-220.
+ /// The semantics of this method are defined by JSR-220.
/// </summary>
/// <param name="obj">a transient instance to be made persistent </param>
void Persist(object obj);
@@ -444,9 +446,9 @@
/// <summary>
/// Copy the state of the given object onto the persistent object with the same
- /// identifier. If there is no persistent instance currently associated with
- /// the session, it will be loaded. Return the persistent instance. If the
- /// given instance is unsaved or does not exist in the database, save it and
+ /// identifier. If there is no persistent instance currently associated with
+ /// the session, it will be loaded. Return the persistent instance. If the
+ /// given instance is unsaved or does not exist in the database, save it and
/// return it as a newly persistent instance. Otherwise, the given instance
/// does not become associated with the session.
/// </summary>
@@ -456,8 +458,8 @@
object SaveOrUpdateCopy(object obj);
/// <summary>
- /// Copy the state of the given object onto the persistent object with the
- /// given identifier. If there is no persistent instance currently associated
+ /// Copy the state of the given object onto the persistent object with the
+ /// given identifier. If there is no persistent instance currently associated
/// with the session, it will be loaded. Return the persistent instance. If
/// there is no database row with the given identifier, save the given instance
/// and return it as a newly persistent instance. Otherwise, the given instance
@@ -484,7 +486,7 @@
/// an instance associated with the receiving <see cref="ISession"/> or a transient
/// instance with an identifier associated with existing persistent state.
/// This operation cascades to associated instances if the association is mapped
- /// with <tt>cascade="delete"</tt>.
+ /// with <tt>cascade="delete"</tt>.
/// </summary>
/// <param name="entityName">The entity name for the instance to be removed. </param>
/// <param name="obj">the instance to be removed </param>
@@ -522,8 +524,8 @@
/// <param name="lockMode">The lock level</param>
void Lock(object obj, LockMode lockMode);
- /// <summary>
- /// Obtain the specified lock level upon the given object.
+ /// <summary>
+ /// Obtain the specified lock level upon the given object.
/// </summary>
/// <param name="entityName">The Entity name.</param>
/// <param name="obj">a persistent or transient instance </param>
@@ -629,8 +631,8 @@
/// <returns>An ICriteria object</returns>
ICriteria CreateCriteria(System.Type persistentClass, string alias);
- /// <summary>
- /// Create a new <c>Criteria</c> instance, for the given entity name.
+ /// <summary>
+ /// Create a new <c>Criteria</c> instance, for the given entity name.
/// </summary>
/// <param name="entityName">The name of the entity to Query</param>
/// <returns>An ICriteria object</returns>
@@ -638,7 +640,7 @@
/// <summary>
/// Create a new <c>Criteria</c> instance, for the given entity name,
- /// with the given alias.
+ /// with the given alias.
/// </summary>
/// <param name="entityName">The name of the entity to Query</param>
/// <param name="alias">The alias of the entity</param>
@@ -720,10 +722,10 @@
/// <returns>a persistent instance or null</returns>
object Get(System.Type clazz, object id, LockMode lockMode);
- /// <summary>
+ /// <summary>
/// Return the persistent instance of the given named entity with the given identifier,
/// or null if there is no such persistent instance. (If the instance, or a proxy for the
- /// instance, is already associated with the session, return that instance or proxy.)
+ /// instance, is already associated with the session, return that instance or proxy.)
/// </summary>
/// <param name="entityName">the entity name </param>
/// <param name="id">an identifier </param>
@@ -740,7 +742,7 @@
/// </summary>
T Get<T>(object id, LockMode lockMode);
- /// <summary>
+ /// <summary>
/// Return the entity name for a persistent entity
/// </summary>
/// <param name="obj">a persistent entity</param>
@@ -794,7 +796,7 @@
/// Implementors of the <seealso cref="ISession"/> interface should return the NHibernate implementation of this method.
/// </remarks>
/// <returns>
- /// An NHibernate implementation of the <seealso cref="ISessionImplementor"/> interface
+ /// An NHibernate implementation of the <seealso cref="ISessionImplementor"/> interface
/// </returns>
ISessionImplementor GetSessionImplementation();
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
