Skip to content

Commit

Permalink
Merge pull request #88 from FabioBatSilva/patch-7
Browse files Browse the repository at this point in the history 
Docs for Named Native Query
  • Loading branch information
@guilhermeblanco
guilhermeblanco committed Apr 16, 2012
2 parents 543a3dd + 58d4b2a commit 4debe46
Show file tree
Hide file tree
Showing 2 changed files with 694 additions and 0 deletions.
220 changes: 220 additions & 0 deletions en/reference/annotations-reference.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,13 @@ Index
-----

- :ref:`@Column <annref_column>`
- :ref:`@ColumnResult <annref_column_result>`
- :ref:`@ChangeTrackingPolicy <annref_changetrackingpolicy>`
- :ref:`@DiscriminatorColumn <annref_discriminatorcolumn>`
- :ref:`@DiscriminatorMap <annref_discriminatormap>`
- :ref:`@Entity <annref_entity>`
- :ref:`@EntityResult <annref_entity_result>`
- :ref:`@FieldResult <annref_field_result>`
- :ref:`@GeneratedValue <annref_generatedvalue>`
- :ref:`@HasLifecycleCallbacks <annref_haslifecyclecallbacks>`
- :ref:`@Index <annref_index>`
Expand All @@ -22,6 +25,7 @@ Index
- :ref:`@ManyToOne <annref_manytoone>`
- :ref:`@ManyToMany <annref_manytomany>`
- :ref:`@MappedSuperclass <annref_mappedsuperclass>`
- :ref:`@NamedNativeQuery <annref_named_native_query>`
- :ref:`@OneToOne <annref_onetoone>`
- :ref:`@OneToMany <annref_onetomany>`
- :ref:`@OrderBy <annref_orderby>`
Expand All @@ -33,6 +37,7 @@ Index
- :ref:`@PreRemove <annref_preremove>`
- :ref:`@PreUpdate <annref_preupdate>`
- :ref:`@SequenceGenerator <annref_sequencegenerator>`
- :ref:`@SqlResultSetMapping <annref_sql_resultset_mapping>`
- :ref:`@Table <annref_table>`
- :ref:`@UniqueConstraint <annref_uniqueconstraint>`
- :ref:`@Version <annref_version>`
Expand Down Expand Up @@ -109,6 +114,17 @@ Examples:
*/
protected $height;
.. _annref_column_result:

@ColumnResult
~~~~~~~~~~~~~~
References name of a column in the SELECT clause of a SQL query.
Scalar result types can be included in the query result by specifying this annotation in the metadata.

Required attributes:

- **name**: The name of a column in the SELECT clause of a SQL query

.. _annref_changetrackingpolicy:

@ChangeTrackingPolicy
Expand Down Expand Up @@ -219,6 +235,39 @@ Example:
//...
}
.. _annref_entity_result:

@EntityResult
~~~~~~~~~~~~~~
References an entity in the SELECT clause of a SQL query.
If this annotation is used, the SQL statement should select all of the columns that are mapped to the entity object.
This should include foreign key columns to related entities.
The results obtained when insufficient data is available are undefined.

Required attributes:

- **entityClass**: The class of the result.

Optional attributes:

- **fields**: Array of @FieldResult, Maps the columns specified in the SELECT list of the query to the properties or fields of the entity class.
- **discriminatorColumn**: Specifies the column name of the column in the SELECT list that is used to determine the type of the entity instance.

.. _annref_field_result:

@FieldResult
~~~~~~~~~~~~~
Is used to map the columns specified in the SELECT list of the query to the properties or fields of the entity class.

Required attributes:

- **name**: Name of the persistent field or property of the class.


Optional attributes:

- **column**: Name of the column in the SELECT clause.

.. _annref_generatedvalue:

@GeneratedValue
Expand Down Expand Up @@ -597,6 +646,77 @@ Example:
// ... fields and methods
}
.. _annref_named_native_query:

@NamedNativeQuery
~~~~~~~~~~~~~~~~~
Is used to specify a native SQL named query.
The NamedNativeQuery annotation can be applied to an entity or mapped superclass.

Required attributes:

- **name**: The name used to refer to the query with the EntityManager methods that create query objects.
- **query**: The SQL query string.


Optional attributes:

- **resultClass**: The class of the result.
- **sqlResultSetMapping**: The name of a SqlResultSetMapping, as defined in metadata.


Example:

.. code-block:: php
<?php
/**
* @NamedNativeQueries({
* @NamedNativeQuery(
* name = "fetchJoinedAddress",
* resultSetMapping= "mappingJoinedAddress",
* query = "SELECT u.id, u.name, u.status, a.id AS a_id, a.country, a.zip, a.city FROM cms_users u INNER JOIN cms_addresses a ON u.id = a.user_id WHERE u.username = ?"
* ),
* })
* @SqlResultSetMappings({
* @SqlResultSetMapping(
* name = "mappingJoinedAddress",
* entities= {
* @EntityResult(
* entityClass = "__CLASS__",
* fields = {
* @FieldResult(name = "id"),
* @FieldResult(name = "name"),
* @FieldResult(name = "status"),
* @FieldResult(name = "address.zip"),
* @FieldResult(name = "address.city"),
* @FieldResult(name = "address.country"),
* @FieldResult(name = "address.id", column = "a_id"),
* }
* )
* }
* )
* })
*/
class User
{
/** @Id @Column(type="integer") @GeneratedValue */
public $id;
/** @Column(type="string", length=50, nullable=true) */
public $status;
/** @Column(type="string", length=255, unique=true) */
public $username;
/** @Column(type="string", length=255) */
public $name;
/** @OneToOne(targetEntity="Address") */
public $address;
// ....
}
.. _annref_onetoone:

@OneToOne
Expand Down Expand Up @@ -801,6 +921,106 @@ Example:
*/
protected $id = null;
.. _annref_sql_resultset_mapping:

@SqlResultSetMapping
~~~~~~~~~~~~~~~~~~~~
The SqlResultSetMapping annotation is used to specify the mapping of the result of a native SQL query.
The SqlResultSetMapping annotation can be applied to an entity or mapped superclass.

Required attributes:

- **name**: The name given to the result set mapping, and used to refer to it in the methods of the Query API.


Optional attributes:

- **resultClass**: Array of @EntityResult, Specifies the result set mapping to entities.
- **columns**: Array of @ColumnResult, Specifies the result set mapping to scalar values.

Example:

.. code-block:: php
<?php
/**
* @NamedNativeQueries({
* @NamedNativeQuery(
* name = "fetchUserPhonenumberCount",
* resultSetMapping= "mappingUserPhonenumberCount",
* query = "SELECT id, name, status, COUNT(phonenumber) AS numphones FROM cms_users INNER JOIN cms_phonenumbers ON id = user_id WHERE username IN (?) GROUP BY id, name, status, username ORDER BY username"
* ),
* @NamedNativeQuery(
* name = "fetchMultipleJoinsEntityResults",
* resultSetMapping= "mappingMultipleJoinsEntityResults",
* query = "SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM cms_users u INNER JOIN cms_addresses a ON u.id = a.user_id INNER JOIN cms_phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username"
* ),
* })
* @SqlResultSetMappings({
* @SqlResultSetMapping(
* name = "mappingUserPhonenumberCount",
* entities= {
* @EntityResult(
* entityClass = "User",
* fields = {
* @FieldResult(name = "id"),
* @FieldResult(name = "name"),
* @FieldResult(name = "status"),
* }
* )
* },
* columns = {
* @ColumnResult("numphones")
* }
* ),
* @SqlResultSetMapping(
* name = "mappingMultipleJoinsEntityResults",
* entities= {
* @EntityResult(
* entityClass = "__CLASS__",
* fields = {
* @FieldResult(name = "id", column="u_id"),
* @FieldResult(name = "name", column="u_name"),
* @FieldResult(name = "status", column="u_status"),
* }
* ),
* @EntityResult(
* entityClass = "Address",
* fields = {
* @FieldResult(name = "id", column="a_id"),
* @FieldResult(name = "zip", column="a_zip"),
* @FieldResult(name = "country", column="a_country"),
* }
* )
* },
* columns = {
* @ColumnResult("numphones")
* }
* )
*})
*/
class User
{
/** @Id @Column(type="integer") @GeneratedValue */
public $id;
/** @Column(type="string", length=50, nullable=true) */
public $status;
/** @Column(type="string", length=255, unique=true) */
public $username;
/** @Column(type="string", length=255) */
public $name;
/** @OneToMany(targetEntity="Phonenumber") */
public $phonenumbers;
/** @OneToOne(targetEntity="Address") */
public $address;
// ....
}
.. _annref_table:

@Table
Expand Down

0 comments on commit 4debe46

Please sign in to comment.