Skip to content

Sync EN: mongodb driver Cursor, CursorId, CursorInterface #750

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
lacatoire wants to merge 1 commit into from
Closed

Sync EN: mongodb driver Cursor, CursorId, CursorInterface #750

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 44 additions & 46 deletions reference/mongodb/mongodb/driver/cursor.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4639881688d3faaf0073ad71fe0a4b730aea15a0 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: lacatoire Status: ready --><!-- CREDITS: leonardolara -->

<reference xml:id="class.mongodb-driver-cursor" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

Expand All @@ -11,12 +11,12 @@
<!-- {{{ MongoDB\Driver\Cursor intro -->
<section xml:id="mongodb-driver-cursor.intro">
&reftitle.intro;
<para>
<simpara>
A classe <classname>MongoDB\Driver\Cursor</classname> encapsula
os resultados de um comando ou consulta MongoDB e podem ser retornados por
<methodname>MongoDB\Driver\Manager::executeCommand</methodname> ou
<methodname>MongoDB\Driver\Manager::executeQuery</methodname>, respectivamente.
</para>
</simpara>
</section>
<!-- }}} -->

Expand Down Expand Up @@ -49,53 +49,51 @@

<section role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongodb 1.9.0</entry>
<entry>
Implementa <interfacename>Iterator</interfacename>.
</entry>
</row>
<row>
<entry>PECL mongodb 1.6.0</entry>
<entry>
Implementa <interfacename>MongoDB\Driver\CursorInterface</interfacename>,
que estende <interfacename>Traversable</interfacename>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongodb 1.9.0</entry>
<entry>
Implementa <interfacename>Iterator</interfacename>.
</entry>
</row>
<row>
<entry>PECL mongodb 1.6.0</entry>
<entry>
Implementa <interfacename>MongoDB\Driver\CursorInterface</interfacename>,
que estende <interfacename>Traversable</interfacename>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

<section xml:id="mongodb-driver-cursor.examples">
&reftitle.examples;

<example xml:id="mongodb-driver-cursor.examples.foreach">
<title>Lendo um conjunto de resultados</title>
<para>
<simpara>
<methodname>MongoDB\Driver\Manager::executeCommand</methodname> e
<methodname>MongoDB\Driver\Manager::executeQuery</methodname> ambos retornam
seus resultados como um objeto <classname>MongoDB\Driver\Cursor</classname>.
Este objeto pode ser usado para iterar sobre conjunto de resultados do comando
ou consulta.
</para>
<para>
</simpara>
<simpara>
Como <classname>MongoDB\Driver\Cursor</classname> implementa a
interface <interfacename>Traversable</interfacename>, pode-se simplesmente
iterar pelo conjunto de resultados com
<link linkend="control-structures.foreach"><literal>foreach</literal></link>.
</para>
</simpara>
<programlisting role="php">
<![CDATA[
<?php
Expand Down Expand Up @@ -154,15 +152,15 @@ stdClass Object

<example xml:id="mongodb-driver-cursor.examples.tailable">
<title>Lendo um conjunto de resultados com um cursor adaptável</title>
<para>
<simpara>
<link xlink:href="&url.mongodb.docs;core/tailable-cursors">Cursores adaptáveis</link>
são um tipo especial de cursor no MongoDB que permite ao cliente ler alguns
resultados e então esperar até que mais documentos fiquem disponíveis. Esses cursores
são usado principalmente com
<link xlink:href="&url.mongodb.docs;core/capped-collections">Coleções Limitadas</link>
e <link xlink:href="&url.mongodb.docs;changeStreams">Fluxos de Alterações</link>.
</para>
<para>
</simpara>
<simpara>
Enquanto os cursores normais podem ser iterados com <literal>foreach</literal>,
esse método não irá funcionar com cursores adaptáveis. Quando
<literal>foreach</literal> é usado com um cursor adaptável, a repetição irá
Expand All @@ -172,21 +170,21 @@ stdClass Object
retroceder o cursor. De forma similar aos objetos de resultados em outros drivers de bancos de dados,
os cursores no MongoDB suportam apenas iteração para a frente, ou seja, eles não podem
ser retrocedidos.
</para>
<para>
</simpara>
<simpara>
Para ler continuamente a partir de um cursor adaptável, o objeto Cursor
deve ser encapsulado com um <classname>IteratorIterator</classname>. Isso
permite que a aplicação controle diretamente a iteração do cursor, evite
retroceder inadvertidamente o cursor e decida quando esperar por novos resultados
ou interromper totalmente a iteração.
</para>
<para>
</simpara>
<simpara>
Para demonstrar um cursor adaptável em ação, serão utilizados dois
scripts: um "produtor" e um "consumidor". O script produtor criará uma nova
coleção limitada usando o
comando <link xlink:href="&url.mongodb.docs.command;create">create</link>
e procederá à inserção de um novo documento nessa coleção a cada segundo.
</para>
</simpara>
<programlisting role="php">
<![CDATA[
<?php
Expand All @@ -210,12 +208,12 @@ while (true) {
?>
]]>
</programlisting>
<para>
<simpara>
Com o script produtor ainda em execução, um segundo script consumidor pode ser
executado para ler os documentos inseridos usando um cursor adaptável, indicado
pelas opções <literal>tailable</literal> e <literal>awaitData</literal>
para o método <function>MongoDB\Driver\Query::__construct</function>.
</para>
</simpara>
<programlisting role="php">
<![CDATA[
<?php
Expand Down Expand Up @@ -245,15 +243,15 @@ while (true) {
?>
]]>
</programlisting>
<para>
<simpara>
O script consumidor começará mostrando rapidamente todos os documentos disponíveis
na coleção limitada (como se <literal>foreach</literal> tivesse sido usado);
entretanto, ele não terminará ao atingir o final do conjunto de resultados inicial.
Como o cursor pode ser seguido, chamar
<function>IteratorIterator::next</function> bloqueará e aguardará
resultados adicionais. <function>IteratorIterator::valid</function> também é
usado para verificar se realmente há dados disponíveis para leitura em cada etapa.
</para>
</simpara>
<note>
<simpara>
Este exemplo usa a opção de consulta <literal>awaitData</literal> para
Expand Down
6 changes: 3 additions & 3 deletions reference/mongodb/mongodb/driver/cursor/construct.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 7d88708b86fa2e642dc3b5c1d9903a149aa0c185 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: lacatoire Status: ready --><!-- CREDITS: leonardolara -->

<refentry xml:id="mongodb-driver-cursor.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand All @@ -13,10 +13,10 @@
<modifier>final</modifier> <modifier>private</modifier> <methodname>MongoDB\Driver\Cursor::__construct</methodname>
<void />
</methodsynopsis>
<para>
<simpara>
Objetos <classname>MongoDB\Driver\Cursor</classname> são retornados como o o
resultado de consultas ou comandos executados e não podem ser construídos diretamente.
</para>
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand Down
6 changes: 3 additions & 3 deletions reference/mongodb/mongodb/driver/cursor/current.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 734bafeaf071b78b15d375f9af583befddd8c2a2 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: lacatoire Status: ready --><!-- CREDITS: leonardolara -->
<refentry xml:id="mongodb-driver-cursor.current" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB\Driver\Cursor::current</refname>
Expand All @@ -22,11 +22,11 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Retorna o documento de resultado atual como um array ou objeto, dependendo do
mapa de tipo do cursor. Se a iteração não tiver iniciado ou se a posição atual
não for válida, retorna &null;.
</para>
</simpara>
</refsect1>

<refsect1 role="seealso">
Expand Down
68 changes: 33 additions & 35 deletions reference/mongodb/mongodb/driver/cursor/getid.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4639881688d3faaf0073ad71fe0a4b730aea15a0 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: lacatoire Status: ready --><!-- CREDITS: leonardolara -->

<refentry xml:id="mongodb-driver-cursor.getid" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand All @@ -13,10 +13,10 @@
<modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\BSON\Int64</type><methodname>MongoDB\Driver\Cursor::getId</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
Retorna o ID para este cursor, que identifica de forma única o cursor no
servidor.
</para>
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -26,10 +26,10 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Retorna o ID para este cursor. O ID será retornado como um
objeto <classname>MongoDB\BSON\Int64</classname>.
</para>
</simpara>
</refsect1>

<refsect1 role="errors">
Expand All @@ -41,36 +41,34 @@

<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongodb 2.0.0</entry>
<entry>
O tipo de retorno foi alterado para <classname>MongoDB\BSON\Int64</classname>.
O parâmetro <parameter>asInt64</parameter> foi removido.
</entry>
</row>
<row>
<entry>PECL mongodb 1.20.0</entry>
<entry>
O retorno de um <classname>MongoDB\Driver\CursorId</classname> foi descontinuado.
Adicionado o parâmetro <parameter>asInt64</parameter> para facilitar a migração para
versões futuras. Se <parameter>asInt64</parameter> for &true;, o ID
será retornado como um <classname>MongoDB\BSON\Int64</classname>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongodb 2.0.0</entry>
<entry>
O tipo de retorno foi alterado para <classname>MongoDB\BSON\Int64</classname>.
O parâmetro <parameter>asInt64</parameter> foi removido.
</entry>
</row>
<row>
<entry>PECL mongodb 1.20.0</entry>
<entry>
O retorno de um <classname>MongoDB\Driver\CursorId</classname> foi descontinuado.
Adicionado o parâmetro <parameter>asInt64</parameter> para facilitar a migração para
versões futuras. Se <parameter>asInt64</parameter> for &true;, o ID
será retornado como um <classname>MongoDB\BSON\Int64</classname>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
Expand Down
10 changes: 5 additions & 5 deletions reference/mongodb/mongodb/driver/cursor/getserver.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 2de5fb458e886b011050a210c6f406ca9ed51c75 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: lacatoire Status: ready --><!-- CREDITS: leonardolara -->

<refentry xml:id="mongodb-driver-cursor.getserver" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand All @@ -13,12 +13,12 @@
<modifier>final</modifier> <modifier>public</modifier> <type>MongoDB\Driver\Server</type><methodname>MongoDB\Driver\Cursor::getServer</methodname>
<void />
</methodsynopsis>
<para>
<simpara>
Retorna o <classname>MongoDB\Driver\Server</classname> associado a este
cursor. Este é o servidor que executou a
<classname>MongoDB\Driver\Query</classname> ou o
<classname>MongoDB\Driver\Command</classname>.
</para>
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -28,10 +28,10 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Retorna o <classname>MongoDB\Driver\Server</classname> associado a este
cursor.
</para>
</simpara>
</refsect1>

<refsect1 role="errors">
Expand Down
10 changes: 5 additions & 5 deletions reference/mongodb/mongodb/driver/cursor/isdead.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 1e327d12051bfc071aea2910c285dd9385565609 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: lacatoire Status: ready --><!-- CREDITS: leonardolara -->

<refentry xml:id="mongodb-driver-cursor.isdead" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand All @@ -13,13 +13,13 @@
<modifier>final</modifier> <modifier>public</modifier> <type>bool</type><methodname>MongoDB\Driver\Cursor::isDead</methodname>
<void />
</methodsynopsis>
<para>
<simpara>
Verifica se definitivamente não há resultados adicionais disponíveis no
cursor. Este método é semelhante ao método
<link xlink:href="&url.mongodb.docs;reference/method/cursor.isExhausted/">cursor.isExhausted()</link>
no shell do MongoDB e é útil principalmente ao iterar
<link xlink:href="&url.mongodb.docs;core/tailable-cursors/">cursores adaptáveis</link>.
</para>
</simpara>
<para>
Um cursor não tem resultados adicionais e é considerado "morto" quando uma das seguintes
opções for verdadeira:
Expand Down Expand Up @@ -62,10 +62,10 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Retorna &true; se definitivamente não houver resultados adicionais disponíveis no
cursor e &false; caso contrário.
</para>
</simpara>
</refsect1>

<refsect1 role="errors">
Expand Down
Loading
Loading