Exception msgs, Mongo descs, and gridfs example

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@290378 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Kristina Chodorow 2009-11-06 17:47:24 +00:00
parent 412c8465bf
commit 2affc9affe
5 changed files with 278 additions and 2 deletions

View file

@ -13,6 +13,64 @@
<modifier>public</modifier> <type>boolean</type><methodname>Mongo::close</methodname>
<void/>
</methodsynopsis>
<para>
This method does not need to be called, except in unusual
circumstances. The driver will cleanly close the database
connection when the Mongo object goes out of scope.
</para>
<para>
If you are using a service where objects do not go out of scope
between requests, you may wish to call close() at the end of
your program to keep old connections from hanging around.
However, it is probably more efficient to take advantage of
this fact and simply use a persistent connection, which will
automatically create a connection if needed and use it for as
many requests as the application server allows it to exist.
</para>
<para>
You may also wish to call close() if you are unsure of the
state of a connection and wish to guarantee a new connection will
happen. For example:
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$mongo = new Mongo();
/* do stuff where the db connection may be lost */
/* if $mongo is already connected, does nothing */
$mongo->connect();
?>
]]>
</programlisting>
</informalexample>
<para>
vs.
</para>
<informalexample>
<programlisting>
<![CDATA[
<?php
$mongo = new Mongo();
/* do stuff where the db connection may be lost */
/* guarantee a reconnection to the db server */
$mongo->close()
$mongo->connect();
?>
]]>
</programlisting>
</informalexample>
</refsect1>
<refsect1 role="parameters">

View file

@ -16,6 +16,32 @@
<methodparam choice="opt"><type>boolean</type><parameter>persistent</parameter><initializer>&false;</initializer></methodparam>
<methodparam choice="opt"><type>boolean</type><parameter>paired</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
<para>
If you elect not to connect immediately, you will need to call
<function>connect</function>, <function>persistConnect</function>,
<function>pairConnect</function>, or
<function>pairPersistConnect</function> before doing any
database operations.
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$mongo = new Mongo("localhost", false);
// throws a MongoException, as $mongo has not been fully initialized yet
$mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age"));
// okay
$mongo->connect();
$mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age"));
?>
]]>
</programlisting>
</informalexample>
</refsect1>
<refsect1 role="parameters">

View file

@ -14,6 +14,112 @@
<para>
Thrown when the driver fails to connect to the database.
</para>
<para>
There are a number of possible error messages, to attempt
to help you diagnose the connection problem. These are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>No server name given.</literal>
</para>
<para>
This error occurs if you pass in "" as the server name,
probably because of an typo with string interpolation,
e.g., "$servr" instead of "$server".
</para>
</listitem>
<listitem>
<para>
<literal>
failed to get left host [hostname] or port [portnum]
from [server].
</literal>
</para>
<para>
<literal>
failed to get right host [hostname] or port [portnum]
from [server].
</literal>
</para>
<para>
This indicated that the first or second server
respectively in a "server1,server2" connection string
was malformed. "[hostname]" and "[portnum]" will be as
much as the driver could dicipher of it.
</para>
</listitem>
<listitem>
<para>
<literal>
failed to get host [hostname] or port [portnum]
from [server].
</literal>
</para>
<para>
This indicated that the server string was malformed.
"[hostname]" and "[portnum]" will be as much as the
driver could dicipher of it.
</para>
</listitem>
<listitem>
<para>
<literal>paired connection, but no right host given</literal>
</para>
<para>
The user attempted to create a paired connection but
passed a string that only listed one server to connect to.
</para>
</listitem>
<listitem>
<para>
<literal>Operation in progress</literal>
</para>
<para>
Connecting to the database timed out.
</para>
</listitem>
<listitem>
<para>
<literal>More links than your body has room for: N of M</literal>
</para>
<para>
N is the number of open connections and M is the
maximum number of connections allowed. By default,
the driver allows unlimited simultaneous connections
to the database. If you wish to limit them, you can set
mongo.max_connections and/or mongo.max_persistent (for
limiting perisistent connections). If you try to create
more than that number of connections, you will get this
error.
</para>
</listitem>
<listitem>
<para>
<literal>couldn't determine master</literal>
</para>
<para>
Neither server in a paired connection appeared to be master.
</para>
</listitem>
<listitem>
<para>
<literal>couldn't get host info for [server]</literal>
</para>
<para>
This indicated that DNS could not resolve the server address
you gave. This could easily be caused by a typo, for example,
"server" instead of "$server".
</para>
</listitem>
</itemizedlist>
<para>
If the error message is not listed above, it is probably an error
from the C socket, and you can search the web for its usual cause.
</para>
</section>
<!-- }}} -->

View file

@ -12,8 +12,66 @@
<section xml:id="mongocursorexception.intro">
&reftitle.intro;
<para>
Thrown by accessing a cursor incorrectly.
Caused by accessing a cursor incorrectly or a error receiving a reply.
</para>
<para>
If there is an error receiving a reply, there will be a more
specific error message to help diagnose the problem:
</para>
<itemizedlist>
<listitem>
<para>
<literal>could not establish db connection</literal>
</para>
<para>
A database reply could not be recieved because a connection
with the database could not be established.
</para>
</listitem>
<listitem>
<para>
<literal>no db response</literal>
</para>
<para>
This may not even be an error, for example, the database
command "shutdown" returns no response. However, if you
were expecting a response, this means the database didn't
give one.
</para>
</listitem>
<listitem>
<para>
<literal>bad response length: %d, max: %d, did the db assert?</literal>
</para>
<para>
This means that the database said that its response was
greater than 4Mb or less than 0. Generally, a number
greater than 5Mb should be reported to the developers as a
potential database bug (max response length is 4Mb). A
response of less than 0 often means a database assertion
occured.
</para>
</listitem>
<listitem>
<para>
<literal>incomplete response</literal>
</para>
<para>
Occurs if the database response is malformed.
</para>
</listitem>
<listitem>
<para>
<literal>[WSA ]error getting database response: errstr</literal>
</para>
<para>
"errstr" is an io error reported directly from the C socket
subsystem. On Windows, is prefixed with "WSA".
</para>
</listitem>
</itemizedlist>
</section>
<!-- }}} -->

View file

@ -12,8 +12,36 @@
<section xml:id="mongogridfs.intro">
&reftitle.intro;
<para>
Utilities for storing and retrieving files from the database.
Utilities for storing and retrieving files from the database.
</para>
<para>
<classname>MongoGridFS</classname> extends
<classname>MongoCollection</classname>, so any of the methods
in <classname>MongoCollection</classname> can be used to
manipulate metadata. For example:
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
// save a file
$id = $grid->storeFile("game.tgz");
$game = $grid->findOne();
// add a downloads counter
$game->file['downloads'] = 0;
$grid->save($game->file);
// increment the counter
$grid->update(array("_id" => $id), array('$inc' => array("downloads" => 1)));
?>
]]>
</programlisting>
</informalexample>
</section>
<!-- }}} -->