The code for getProfile is straightforward. First, some simple validation is performed on the parameters, and then a database connection is prepared with a simple SQL statement:

def getProfile(self, strId, dom=0):
  """
  getProfile - returns an XML profile chunk based on
  the supplied id.  Returns None if not found.
  """
  if not strId:
    return None

  # generate connection
  conn = odbc.odbc(CONNECTION_STRING)
  cmd = conn.cursor(  )
  cmd.execute("select * from customer where " +
              "customerId = '" + strId + "'")
  conn.close(  )

In this code, that strId is inspected before anything else occurs, and the database command is of a simple select * variety. Of note is the third default parameter, dom=0, present in the method definition. This is flipped on by getProfileAsDom to require that getProfile return a DOM instance instead of a string.

Next, the record is retrieved, and an XML document is prepared using the DOMImplementation class.

# get data record
prof_fields = cmd.fetchone(  )
if prof_fields is None:
  return None

# generate XML from fields
# generate CustomerProfile doctype
doctype = implementation.createDocumentType(
  "CustomerProfile", "", "CustomerProfile.dtd")

# generate new document with doctype
newdoc = implementation.createDocument(
  "", "CustomerProfile", doctype)
rootelem = newdoc.documentElement

# create root element id attribute
rootelem.setAttribute("id", prof_fields[CUSTOMER_ID])

In this code, the DOMImplementation class is used to build an XML document. In the beginning of the snippet, prof_fields is populated with the raw list of values from the database using the fetchone method, which returns one row. The indexes into prof_fields are given as named constants defined in the CustomerProfile module; the definitions are listed in the complete source listing for the module in Example 10-2, later in this chapter. Next, a document type object is created, citing the CustomerProfile.dtd file created earlier. This object is then used in the call to implementation.createDocument to generate an empty XML document element.

At this point, the simplicity of using the DOMImplementation to build your XML document (as opposed to manually constructing a string of XML, which is done later) is illustrated when we construct the elements in a simple loop:

# create list with field values
fields = ["firstname", prof_fields[FIRSTNAME],
          "lastname",  prof_fields[LASTNAME],
          "address1",  prof_fields[ADDRESS1],
          "address2",  prof_fields[ADDRESS2],
          "city",      prof_fields[CITY],
          "state",     prof_fields[STATE],
          "zip",       prof_fields[ZIP],
          ]
# loop through list adding elements and element text
for pos in range(0, len(fields), 2):
  # create the element
  thisElement = newdoc.createElement(fields[pos])

  # check for empty values and convert to soft nulls
  if fields[pos + 1] is None:
    fields[pos + 1] = ""
  thisElement.appendChild(newdoc.createTextNode(fields[pos+1]))
  rootelem.appendChild(thisElement)

What is interesting about this code is that you place all of the database values in a list, and then iterate the list creating and appending elements as you go. Use a list to hold the data values instead of a dictionary, because you need to create elements in the XML document in a specific order or it won’t comply with the DTD. (Python dictionaries return their keys in an unpredictable order, and certainly do not maintain the order in which you inserted them).

Using a list over a dictionary poses no big feat, as the Python range function is used to hop through the list in steps of two, allowing the code to use the current list member as the element name, and the next list member as the element’s character data content.

With the XML in hand, a decision is made whether to return a string of XML or a DOM, based on how the method was called (remember, getProfileAsDom calls getProfile with additional parameters):

# return DOM or String based on how we were called...
if dom:
  return newdoc
else:
  # return string
  strXML = StringIO.StringIO(  )
  PrettyPrint(newdoc, strXML)
  return strXML.getvalue(  )

At this point, the caller’s request has been satisfied. If a string is returned, the StringIO class is used in conjunction with the PrettyPrint method to write the XML into the string as if it were a file. Using a DOMImplementation to create your document, as opposed to manually constructing one with a string, offers several benefits. First, it removes tricky details such as preparing a DTD and encoding declarations from inside string assignment statements. It’s far easier to maintain the code if you can programmatically alter the encoding or Document Type, without resorting to editing XML by hand inside string assignment statements. Second, greater flexibility is enabled if you need to change the structure of the document. It’s easier in the long run to manipulate nodes and their position in the document with a DOM than to parse and manipulate a text string. However, there are many times when you may want to concatenate a string of XML together and create a fresh DOM (in this case, you still wind up with a programmatically accessible DOM representation of the XML).

Using getProfileAsDom works the same as getProfile, but a DOM instance is returned to you instead of a string of XML.

def getProfileAsDom(self, strId):
  """
  This method calls getProfile with the
  dom option set on, which causes getProfile
  to return its created DOM object, and not
  an XML string
  """
  return self.getProfile(strId, 1)

This approach was taken because it’s often easier to provide intuitive convenience functions as opposed to loading down a method with conditional parameters that a user must learn.

The code for insertProfile is simple as well, but touches on some intricate DOM manipulation. It starts off, as does getProfile, with some simple validation and the retrieval of a DOM instance (as opposed to a DOMImplementation in getProfile):

def insertProfile(self, strXML):
 """
 insertProfile takes an XML chunk as a string,
  parses down its fields, and inserts it into the
  profile database.  Raises an exception if XML is
  not well-formed, or customer Id is missing, or if
  SQL execution fails.  Returns 1 on success, 0 on failure.
  """
  if not strXML:
    return 0

  # Begin parsing XML
  try:
    doc = FromXml(strXML)
  except:
    print "Error parsing document."
    return 0

  # Normalize white space and retrieve root element
  doc.normalize(  )
  elem = doc.documentElement

Probably the most important things in the preceding code are the calls to FromXml and the call to the normalize method of the instantiated document object. The FromXml method is part of the Sax2 reader package, and allows for the construction of a DOM object from a raw string of XML data.

The call to the doc.normalize method is important as well. The structure of a CustomerProfile XML chunk is quite simple. The character data residing in the elements is short, and needs no peripheral whitespace. That is, if a web form or GUI has placed carriage returns inside the elements, they can be safely eliminated. This step is critical to how the elements are processed inside insertProfile. Without the normalization call, it’s possible that the text contained in the element may be contained in multiple nodes, and the firstChild attribute provides only the first of these; the call to normalize ensures that all adjacent text nodes are collapsed into a single node.

Next, the values are extracted out of the fresh XML DOM and used to populate a SQL statement.

# Extract values from XML packet
customerId = elem.getAttributeNS(None, 'id')
firstname = self.extractNodeValue(elem, "firstname")
lastname  = self.extractNodeValue(elem, "lastname")
address1  = self.extractNodeValue(elem, "address1")
address2  = self.extractNodeValue(elem, "address2")
city      = self.extractNodeValue(elem, "city")
state     = self.extractNodeValue(elem, "state")
zip       = self.extractNodeValue(elem, "zip")

# prepare SQL statement
strSQL = ("insert into Customer values ("
          "'" + firstname  + "', "
          "'" + lastname   + "', "
          "'" + address1   + "', "
          "'" + address2   + "', "
          "'" + city       + "', "
          "'" + state      + "', "
          "'" + zip        + "', "
          "'" + customerId + "')")

Here, the customerId attribute is extracted from the root element, and then a series of calls to the extractNodeValue helper method are issued. This small method (shown next) takes the current element and attempts to extract a target’s text value beneath itself. Since this step is repeated for every element you need, it’s easier to relegate it to an internal function rather than duplicate the code in each method that uses it. The preparation of the SQL statement takes the results of the calls to extractNodeValue and assembles a SQL insert statement. The work of extractNodeValue is shown as follows:

def extractNodeValue(self, elem, elemName):
  """
  Internal method to parse UNIQUE elements for text value or
  substitute empty strings.
  """
  e = elem.getElementsByTagName(elemName)[0].firstChild
  if e is not None:
    return e.nodeValue
  else:
    return ""

This method attempts to extract a child element from the element it is given, and also tests for its character data content. If not available, an empty string is returned.

Now that the SQL statement is prepared, it can be sent to the database:

# generate connection
conn = odbc.odbc(CONNECTION_STRING)
cmd = conn.cursor(  )

# execute SQL statement
if not cmd.execute(strSQL):
  return 0

conn.close(  )
return 1

If communication with the database proceeds as expected, the method returns a positive 1 to the caller.

The code to delete a profile from the database is easy, and relies mainly on taking the supplied customer ID and using it as a parameter in a SQL delete statement:

def deleteProfile(self, strId):
  """
  deleteProfile accepts a customer profile ID
  and deletes the corresponding record in the database.
  Returns 1 on success, 0 on failure.
  """
  if not strId:
    return 0

  # generate database connection
  conn = odbc.odbc(CONNECTION_STRING)
  cmd = conn.cursor(  )
  ok = cmd.execute("delete from customer where customerId = '"
                     + strId + "'"):
  conn.close(  )
  return ok and 1 or 0

The result of the SQL operation is indicated to the caller by either a 1 or 0 return value.