archived-doc-es/reference/mongo/mongocursor.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9f0e1e36a3eeac3652b724a834dbf241a8c90527 Maintainer: seros Status: ready -->
<!-- Reviewed: no -->

<phpdoc:classref xml:id="class.mongocursor" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <title>La clase MongoCursor</title>
 <titleabbrev>MongoCursor</titleabbrev>
 
 <partintro>
  
  <!-- {{{ Mongocursor intro -->
  <section xml:id="mongocursor.intro">
   &reftitle.intro;
   <para>
    Un cursor se utiliza parar recorrer el resultado de una consulta a la base de datos. Por
    ejemplo, para consultar la base de datos y revisar los resultados, se podría hacer lo siguiente:
    <example xml:id="mongocursor.intro-example">
     <title>Uso básico de <classname>MongoCursor</classname></title>
     <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find();
var_dump(iterator_to_array($cursor));

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Por norma general, los cursores no se crean utilizando el constructor
    <classname>MongoCursor</classname>, ya que se obtienen al invicar a
    <function>MongoCollection::find</function> (como en el ejemplo superior).
   </para>
   <para>
    Supóngase que, en el ejemplo superior, <literal>$collection</literal> fuera una
    colección de 50GB. No quisiéramos tener que alojar en memoria todo de una vez,
    y esto es lo que solucionan los cursores: permiten al cliente acceder a la
    colección gota a gota.
   </para>
   <para>
    Si tuviéramos un resultado extenso, podríamos recorrerlo cargando unos pocos
    megabytes a memoria cada vez. Por ejemplo:
    <example>
     <title>Iterar sobre <classname>MongoCursor</classname></title>
     <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find();

foreach ($cursor as $doc) {
    // hacer algo a cada documento
}

?>
]]>
     </programlisting>
    </example>
    Esto recorrerá cada documento de la colección, cargando y eliminando de memoria
    cada documento según se necesite.
   </para>
   <para>
    Debe tenerse en cuenta que esto significa que un cursor no "contiene" el resultado de la base de datos,
    sino que sólo lo gestiona. Por tanto, si se imprimiera un cursor (con, digamos,
    <function>var_dump</function> o <function>print_r</function>), sólo se obtendría
    el propio objeto cursor, sin los documentos. Para obtener los documentos en sí,
    debe utilizarse alguno de los métodos vistos arriba.
   </para>
  </section>
  
  <section>
   <title>Estados de un Cursor</title>
   <para>
    Un <classname>MongoCursor</classname> tiene dos estados: pre y post
    consulta. Al crear un cursor, éste no se conecta a la base de datos, por lo que
    está en estado pre-consulta. En este estado, el cliente puede indicar
    qué quiere consultar, definiendo límites, saltos, ordenaciones y más opciones
    avanzadas.
   </para>
   <para>
    Cuando el cliente solicita el resultado (invocando
    <function>MongoCursor::next</function>, directa o indirectamente), el cursor avanza
    al estado post-consulta. En este punto, la consulta ya se ha ejecutado por la base
    de datos y ya no se puede modificar.
   </para>
   <para>
    <example xml:id="mongocursor.stages.adding-options">
     <title>Añadir opciones a <classname>MongoCursor</classname></title>
     <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find()->limit(10);

// todavía no se ha consultado la base de datos, de modo que se pueden añadir más opciones
$cursor = $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());
// ya se ha consultado la base de datos, y no se pueden añadir más opciones

// por lo que esto lanzaría una excepción:
$cursor->skip(4);
?>
]]>
     </programlisting>
    </example>
   </para>
  </section>
  <!-- }}} -->
  
  <section xml:id="mongocursor.synopsis">
   &reftitle.classsynopsis;
   
   <!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>MongoCursor</classname></ooclass>
    
    <!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <ooclass>
      <classname>MongoCursor</classname>
     </ooclass>
     <oointerface>
      <interfacename>MongoCursorInterface</interfacename>
     </oointerface>
     <oointerface>
      <interfacename>Iterator</interfacename>
     </oointerface>
    </classsynopsisinfo>
    <!-- }}} -->
    
    <classsynopsisinfo role="comment">Campos Estáticos</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>static</modifier>
     <type>boolean</type>
     <varname linkend="mongocursor.props.slaveokay">slaveOkay</varname>
     <initializer>&false;</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>static</modifier>
     <type>integer</type>
     <varname linkend="mongocursor.props.timeout">timeout</varname>
     <initializer>30000</initializer>
    </fieldsynopsis>
    
    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongocursor')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
   </classsynopsis>
   <!-- }}} -->
   
  </section>
  
  <section>
   <title>Variables Estáticas</title>
   
   <variablelist>
    <varlistentry xml:id="mongocursor.props.slaveokay">
     <term><varname>slaveOkay</varname></term>
     <listitem>
      <para>
       Si la consulta debe o no tener asignada la bandera "slaveOkay", la cual permite leer
       el secundario (por omisión, los secundarios son para hacer copias de seguridad, no
       consultas). Puede sobrescribirse con <function>MongoCursor::slaveOkay</function>.
      </para>
      <para>
       Esta funcionalidad es <emphasis>obsoleta</emphasis>. Por favor, use
       <xref linkend="mongo.readpreferences" /> en su lugar.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="mongocursor.props.timeout">
     <term><varname>timeout</varname></term>
     <listitem>
      <para>
       Establecer el tiempo de espera en milisegundos para las respuestas de todas las bases de datos. Use
       <literal>-1</literal> para esperar eternamente. Se puede sobcrescribir con
       <function>MongoCursor::timeout</function>. Esto no hace que el servidor
       de MongoDB cancele la operación; sólo hace que el controlador
       deje de esperar una respuesta y lanza una
       <classname>MongoCursorTimeoutException</classname> después de un tiempo establecido.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>
  
  <section role="seealso">
   &reftitle.seealso;
   <para>
    Documentación de MongoDB sobre <link xlink:href="&url.mongodb.dochub.cursors;">cursores</link>.
   </para>
  </section>
  
 </partintro>
 
 &reference.mongo.entities.mongocursor;
 
</phpdoc:classref>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->