Updating the documentation for using a remote or local server

doc/introduction-to-mongo.tex

@@ -83,14 +83,34 @@ The commands that are given in this document have been tested with MongoDB serve
 
 \section{Server connection details \label{section:connection-details}}
 
-These exercises can be run using a MongoDB server on the local PC or using a remote MongoDB server.  If a remote MongoDB server is used, then the connection details must be provided by setting environment variables as demonstrated in Listing~\ref{listing:envs}, where \texttt{server\_name}, \texttt{username} and \texttt{password} should be replaced by the corresponding connection values.  These variables must be set in the terminal window where the Python example programs are run.
+These exercises can be run using a MongoDB server on the local PC or using a remote MongoDB server.  If a remote MongoDB server is used, then the connection details must be provided by setting environment variables as demonstrated in Listing~\ref{listing:envs}, where \texttt{server\_name}, \texttt{username}, \texttt{password} and \texttt{db\_name} should be replaced by the corresponding connection values.  These variables must be set in the terminal window where the Python example programs are run.  If the environment variables are not set, the default values from Table~\ref{table:env-defaults} are used.
 
 \begin{lstlisting}[caption={Setting connection Bash environment variables.},label=listing:envs,numbers=none,language=Bash,showspaces=true]
 export MONGODB_SERVER=server_name
 export MONGODB_USERNAME=username
 export MONGODB_PASSWD=password
+export MONGODB_DB=db_name
 \end{lstlisting}
 
+\begin{table}[h!!]
+  \begin{center}
+    \caption{Default settings for environment variables.}
+    \label{table:env-defaults}
+    \begin{tabular}{l|l} \hline
+      \textbf{Variable} & \textbf{Default/Action}\\
+      \hline
+      \texttt{MONGODB\_SERVER} & \texttt{localhost} \\
+      \texttt{MONGODB\_USERNAME} & No authentication. \\
+      \texttt{MONGODB\_PASSWD} & No authentication. \\
+      \texttt{MONGODB\_DB} & \texttt{test} \\ \hline
+    \end{tabular}
+  \end{center}
+\end{table}
+
+The environment variables are read by the functions that are defined in \texttt{mongo\_connect.py}.  The functions in \texttt{mongo\_connect.py} are used to connect to the MongoDB database server and select a database.
+
+\clearpage
+
 \section{Exercises}
 
 \begin{enumerate}
@@ -112,39 +132,47 @@ cd introduction-to-mongodb/python
 
 \item Test the connection to the MongoDB server by running the command given in Listing~\ref{listing:test-connection}.  If the client successfully connects to the MongoDB server, the program will print ``Successfully connected to MongoDB server.''
 
-\begin{lstlisting}[caption={Testing the connection to the MongoDB server.},label=listing:test-connection,numbers=none,language=Bash]
+\begin{lstlisting}[caption={Testing the connection to the MongoDB server.},label=listing:test-connection,numbers=none,language=Bash,showspaces=true]
 ./test_connection.py
 \end{lstlisting}
 
 \item List the databases that are available by typing the command given in Listing~\ref{listing:list-databases}.
 
-\begin{lstlisting}[caption={Listing available MongoDB databases.},label=listing:list-databases,numbers=none,language=Bash]
-./test_connection.py
+\begin{lstlisting}[caption={Listing available MongoDB databases.},label=listing:list-databases,numbers=none,language=Bash,showspaces=true]
+./list_databases.py
 \end{lstlisting}
 
-\item At the Bash prompt, type the text given in Listing~\ref{listing:create-database-run}.
+\item Create a database by typing the command that is given in Listing~\ref{listing:create-database-run}.
 %
-\begin{lstlisting}[caption={Running a Python script to create a database.},label=listing:create-database-run,numbers=none,language=Bash]
+\begin{lstlisting}[caption={Running a Python program to create a database.},label=listing:create-database-run,numbers=none,language=Bash,showspaces=true]
 ./create_database.py
 \end{lstlisting}
 %
-The contents of \texttt{create\_database.py} are given in Listing~\ref{listing:create_database.py}.  This Python program opens a client connection to MongoDB, assuming that it is running on the local computer.  It then creates a database called \texttt{'sales'}.  Line 9 either creates the database or forms a connection to it, if it already exists.  A collection is created in a similar manner as a database.  A document is defined as a Python dictionary at Line 15 and 16.  Finally, the Python dictionary is passed to the function \texttt{insert\_one} to insert it into the database.
+The contents of \texttt{create\_database.py} are given in Listing~\ref{listing:create_database.py}.  This Python program opens a client connection to the MongoDB server. It creates a database using the value in the \texttt{MONGODB\_DB} environment variable or the default name \texttt{'test'} if the environment variable has not been set.  Line 8 either creates the database or forms a connection to it, if it already exists.  A collection is created in a similar manner as a database.  A document is defined as a Python dictionary at Line 14 and 15.  Finally, the Python dictionary is passed to the function \texttt{insert\_one} to insert it into the database.
+
+If a collection is created, but it does not contain at least one document it will not be saved to the MongoDB server.  Likewise, if a database does not contain at least one collection, it will not be saved to the MongoDB server.
+
 \clearpage
-\lstinputlisting[caption={The file create\_database.py.},label=listing:create_database.py,language=python]{"../python/create_database.py"}
+
+\lstinputlisting[caption={The file create\_database.py.},label=listing:create_database.py,language=python,showspaces=true]{"../python/create_database.py"}
 
 \item At the Bash prompt, execute the script \texttt{read\_database.py} in a similar manner as Listing~\ref{listing:create-database-run}.
 
-The contents of \texttt{read\_database.py} are given in Listing~\ref{listing:read_database.py}.  This Python program opens a client connection to MongoDB.  Then it gets the \texttt{'sales'} database.  It loops over the collection names in the database, printing each collection name.  If the \texttt{'Customers'} collection does not exist, an Error message is printed and the program stops.  If the \texttt{'Customers'} collection does exist, then each document is printed that is within the collection.  The \texttt{find} function is used at Line 24 without arguments, selecting all documents and fields within the collection.
+The contents of \texttt{read\_database.py} are given in Listing~\ref{listing:read_database.py}.  This Python program opens a client connection to the MongoDB server and gets a connection to the database.  It loops over the collection names in the database, printing each collection name.  If the \texttt{'Customers'} collection does not exist, an error message is printed and the program stops.  If the ``\texttt{Customers}'' collection does exist, then each document from the collection is printed.  The \texttt{find} function is used at Line 23 without arguments, selecting all documents and fields within the collection.
+
 \clearpage
-\lstinputlisting[caption={The file read\_database.py.},label=listing:read_database.py,language=python]{"../python/read_database.py"}
 
-\item Add another document to MongoDB.  First, try to add a document to the \texttt{'Customers'} collection.  Then try to add another collection to the \texttt{'sales'} database.  Finally, try adding another database, collection and document.  (The \texttt{drop\_databases.py} script can be executed to clear MongoDB if needed.  The \texttt{drop\_databases.py} script can be executed in a similar manner as Listing~\ref{listing:create-database-run}.)
+\lstinputlisting[caption={The file read\_database.py.},label=listing:read_database.py,language=python,showspaces=true]{"../python/read_database.py"}
+
+\item Add another document to MongoDB.  First, try to add a document to the \texttt{'Customers'} collection.  Then try to add another collection to the database. 
+
+\item Run the \texttt{drop\_database.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.
 
-\item At the Bash prompt, execute the script \texttt{planets\_database.py} in a similar manner as Listing~\ref{listing:create-database-run}.
+\item Run the \texttt{planets\_database.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.
 
-The contents of \texttt{planets\_database.py} are given in Listing~\ref{listing:planets_database.py}.  This program creates a \texttt{'planets'} database and a \texttt{'OrbitData'} collection.  It reads JSON data from a text file called \texttt{'planets.json'} and inserts these data into MongoDB.
+The contents of \texttt{planets\_database.py} are given in Listing~\ref{listing:planets_database.py}.  This program creates a database and a \texttt{'OrbitData'} collection.  It reads JSON data from a text file named\texttt{'planets.json'} and inserts these data into MongoDB.
 
-The first section of the \texttt{'planets.json'} file is given in Listing~\ref{listing:planets.json}.  This file contains a list, where each element is a dictionary.  The Python program reads these data into a list that contains dictionaries as its elements.  The \texttt{insert\_many} function is called at Line 21 to insert these data into the MongoDB database.
+The first section of the \texttt{'planets.json'} file is given in Listing~\ref{listing:planets.json}.  This file contains a list, where each element is a dictionary.  The Python program reads these data into a list that contains dictionaries as its elements.  The \texttt{insert\_many} function is called at Line 20 to insert these data into the MongoDB database.
 
 \clearpage
 
@@ -152,19 +180,19 @@ The first section of the \texttt{'planets.json'} file is given in Listing~\ref{l
 
 \lstinputlisting[caption={The first 24 lines of the file planets.json.},label=listing:planets.json,language=java,lastline=24]{"../python/planets.json"}
 
-\item At the Bash prompt, execute the script \texttt{select\_planet.py} in a similar manner as Listing~\ref{listing:create-database-run}.
+\item Run the \texttt{select\_planet.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.
 
 The contents of \texttt{select\_planet.py} are given in Listing~\ref{listing:select_planet.py}.  This Python program prints the names of the collections and then checks if the \texttt{'orbit\_data'} collection is present.  If the \texttt{'OrbitData'} collection is present, it prints the names of each of the planets and the complete document for Pluto.
 
-The \texttt{find} function at Line 27 includes two arguments, which are each given within \texttt{\{\}} parentheses.  The first pair of \texttt{\{\}} parentheses is empty.  This is the condition, which is optional.  Since the condition is empty, all documents are considered.  The second argument is \texttt{\{'name':1, '\_id':0 \}}.  The second argument is a list of document fields that should be considered.  The format is the field name, a colon and the position number.  Setting the position number to zero for the \texttt{\_id} field causes it not to be printed.
+The \texttt{find} function at Line 26 includes two arguments, which are each given within \texttt{\{\}} parentheses.  The first pair of \texttt{\{\}} parentheses is empty.  This is the condition, which is optional.  Since the condition is empty, all documents are considered.  The second argument is \texttt{\{'name':1, '\_id':0 \}}.  The second argument is a list of document fields that should be considered.  The format is the field name, a colon and the position number.  Setting the position number to zero for the \texttt{\_id} field causes it not to be printed.
 
-The \texttt{find\_one} function at Line 33 includes a condition that the field 'name' must be equal to 'Pluto'.  Since the list of fields to be considered is omitted, all fields are returned.
+The \texttt{find\_one} function at Line 32 includes a condition that the field \texttt{'name'} must be equal to \texttt{'Pluto'}.  Since the list of fields to be considered is omitted, all fields are returned.
 
 \lstinputlisting[caption={The file select\_planet.py.},label=listing:select_planet.py,language=python]{"../python/select_planet.py"}
 
-\item At the Bash prompt, execute the script \texttt{planets\_with\_moons.py} in a similar manner as Listing~\ref{listing:create-database-run}.
+\item Run the \texttt{planets\_with\_moons.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.
 
-The contents of \texttt{planets\_with\_moons.py} are given in Listing~\ref{listing:planets_with_moons.py}.  This program reads data from the \texttt{'OrbitData'} collection.  The \texttt{find} function at Line 27 is used to list the names of the planets and their number of moons.  The \texttt{find} function at Line 34 contains two arguments.  The text \texttt{\$gt} implies greater than.  Therefore, the condition is that the selected documents must have more than zero moons.  The second argument is used to print the planet name and number of moons.  Finally, the \texttt{sort} function is used to sort the documents by the number of moons.
+The contents of \texttt{planets\_with\_moons.py} are given in Listing~\ref{listing:planets_with_moons.py}.  This program reads data from the \texttt{'OrbitData'} collection.  The \texttt{find} function at Line 25 is used to list the names of the planets and their number of moons.  The \texttt{find} function at Line 32 contains two arguments.  The text \texttt{\$gt} implies greater than.  Therefore, the condition is that the selected documents must have more than zero moons.  The second argument is used to print the planet name and number of moons.  Finally, the \texttt{sort} function is used to sort the documents by the number of moons.
 
 \lstinputlisting[caption={The file planets\_with\_moons.py.},label=listing:planets_with_moons.py,language=python]{"../python/planets_with_moons.py"}
 
@@ -193,15 +221,19 @@ The comparison query operators are provided in Table~\ref{table:comp-operators}
 
 \item Order planets by their mass.
 
-\item At the Bash prompt, execute the script \texttt{index\_database.py} in a similar manner as Listing~\ref{listing:create-database-run}.
+\item Run the \texttt{drop\_database.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.
 
-The contents of \texttt{index\_database.py} are given in Listing~\ref{listing:index_database.py}.  This program creates a database called \texttt{'indexedsales'} and a \texttt{'Customers'} collection.  Before any documents are added, an index is defined at Line 16.  This index requires that \texttt{CustomerName} entries are unique within the collection.  A customer is defined and inserted at Line 24.  If the insert operation fails, the program prints the warning message at Line 27.
+\item Run the \texttt{index\_database.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.
+
+The contents of \texttt{index\_database.py} are given in Listing~\ref{listing:index_database.py}.  This program creates a database and a \texttt{'Customers'} collection.  Before any documents are added, an index is defined at Line~15.  This index requires that \texttt{CustomerName} entries are unique within the collection.  A customer is defined at Line~18 and inserted at Line~23.  If the insert operation fails, the program prints the warning message at Line~26.
 
 \lstinputlisting[caption={The file index\_database.py.},label=listing:index_database.py,language=python]{"../python/index_database.py"}
 
-\item At the Bash prompt, execute the script \texttt{index\_database.py} in a similar manner as Listing~\ref{listing:create-database-run}.  What happened the second time that the program was run?
+\item Run the \texttt{index\_database.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.  What happened the second time that the program was run?
+
+\item Run the script \texttt{drop\_database.py} and then \texttt{index\_database.py} in a similar manner as Listing~\ref{listing:create-database-run}.  What happens this time?
 
-\item At the Bash prompt, execute the script \texttt{drop\_databases.py} and then \texttt{index\_database.py} in a similar manner as Listing~\ref{listing:create-database-run}.  What happens this time?
+\item Run the \texttt{drop\_database.py} program, in a similar manner as Listing~\ref{listing:create-database-run}.
 
 \end{enumerate}