diff options
Diffstat (limited to 'demos/sqlmap/protected/pages/Manual/ParameterMap.page')
| -rw-r--r-- | demos/sqlmap/protected/pages/Manual/ParameterMap.page | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/demos/sqlmap/protected/pages/Manual/ParameterMap.page b/demos/sqlmap/protected/pages/Manual/ParameterMap.page new file mode 100644 index 00000000..de574139 --- /dev/null +++ b/demos/sqlmap/protected/pages/Manual/ParameterMap.page @@ -0,0 +1,184 @@ +<com:TContent ID="body">
+<h1>Parameter Maps and Inline Parameters</h1>
+
+<p>Most SQL statements are useful because we can pass them values at runtime.
+Someone wants a database record with the ID 42, and we need to merge that ID
+number into a select statement. A list of one or more parameters are passed at
+runtime, and each placeholder is replaced in turn. This is simple but labor
+intensive, since developers spend a lot of time counting symbols to make sure
+everything is in sync.</p>
+
+<div class="note"><b class="tip">Note:</b>
+Preceding sections briefly touched on inline parameters, which automatically
+map properties to named parameters. Many iBATIS developers prefer this
+approach. But others prefer to stick to the standard, anonymous approach to
+SQL parameters by using parameter maps. Sometimes people need to retain the
+purity of the SQL statements; other times they need the detailed specification
+offered by parameter maps due to database or provider-specific information
+that needs to be used.
+</div>
+
+<h1>Parameter Map</h1>
+<p>A Parameter Map defines an ordered list of values that match up with the
+placeholders of a parameterized query statement. While the attributes
+specified by the map still need to be in the correct order, each parameter is
+named. You can populate the underlying class in any order, and the Parameter
+Map ensures each value is passed in the correct order.</p>
+
+<p>Parameter Maps can be provided as an external element and \emph{inline}.
+The following example shows an external Parameter Map.</p>
+
+<com:TTextHighlighter Language="xml" CssClass="source">
+<parameterMap id="parameterMapIdentifier"
+ [extends="[sqlMapNamespace.]parameterMapId"]>
+ <parameter
+ property ="propertyName"
+ [column="columnName"]
+ [dbType="databaseType"]
+ [type="propertyCLRType"]
+ [nullValue="nullValueReplacement"]
+ [size="columnSize"]
+ [precision="columnPrecision"]
+ [scale="columnScale"]
+ [typeHandler="class.name"]
+ <parameter ... ... />
+ <parameter ... ... />
+</parameterMap>
+</com:TTextHighlighter>
+
+<p>In the above example, the parts in <tt>[brackets]</tt> are optional. The
+<tt>parameterMap</tt> element only requires the id attribute.
+The following example shows a typical <tt><parameterMap></tt>.</p>
+
+<com:TTextHighlighter Language="xml" CssClass="source">
+<parameterMap id="insert-product-param" class="Product">
+ <parameter property="description" />
+ <parameter property="id"/>
+</parameterMap>
+
+<statement id="insertProduct" parameterMap="insert-product-param">
+ insert into PRODUCT (PRD_DESCRIPTION, PRD_ID) values (?,?);
+</statement>
+</com:TTextHighlighter>
+
+<div class="note"><b class="tip">Note:</b>
+Parameter Map names are always local to the Data Map definition file where
+they are defined. You can refer to a Parameter Map in another Data Map
+definition file by prefixing the <tt>id</tt> of the Parameter Map with the
+namespace of the Data Map (set in the <tt><sqlMap></tt> root element).
+</div>
+
+<h2><tt><parameterMap></tt> attributes</h2>
+
+<p>The <tt><parameterMap></tt> element
+accepts two attributes: <tt>id</tt> (required) and <tt>extends</tt> (optional).</p>
+
+<h3><tt>id</tt> attribute</h3>
+
+<p>The required <tt>id</tt> attribute provides a
+unique identifier for the <tt><parameterMap></tt> within this Data Map.</p>
+
+<h3><tt>extends</tt> attribute</h3>
+<p>The optional <tt>extends</tt> attribute can be set to the name of another
+<tt>parameterMap</tt> upon which to base this <tt>parameterMap</tt>. All properties of
+the super <tt>parameterMap</tt> will be included as part of this
+<tt>parameterMap</tt>, and values from the super <tt>parameterMap</tt> are set before
+any values specified by this <tt>parameterMap</tt>. The effect is similar to
+extending a class.</p>
+
+<h1><tt><parameter></tt> Elements</h1>
+<p>The <tt><parameterMap></tt> element holds one or more parameter child elements
+that map object properties to placeholders in a SQL statement. The sections
+that follow describe each of the attributes.</p>
+
+<h2><tt>property</tt> attribute</h2>
+<p>The <tt>property</tt> attribute of <tt><parameter></tt> is the name of a property of
+the parameter object. It may also be the name of an entry in an array. The
+name can be used more than once depending on the number of times it is needed
+in the statement. (In an update, you might set a column that is also part of
+the where clause.)</p>
+
+<h2><tt>direction</tt> attribute</h2>
+<p>The <tt>direction</tt> attribute may be used to indicate a stored procedure
+parameter's direction.</p>
+
+<!-- tabular: align=|l|l|, width=(0.2 0.4) -->
+<table class="tabular">
+ <tr><th>Value</th><th>Description</th></tr>
+ <tr>
+ <td><tt>Input</tt></td>
+ <td>input-only</td>
+ </tr>
+ <tr>
+ <td><tt>Output</tt></td>
+ <td>output-only</td>
+ </tr>
+ <tr>
+ <td><tt>InputOutput</tt></td>
+ <td>bidirectional</td>
+ </tr>
+</table>
+
+<h2><tt>column</tt> attribute</h2>
+<p>The <tt>column</tt> attribute is used to define to the name of a parameter used by
+a stored procedure.</p>
+
+<h2><tt>dbType</tt> attribute</h2>
+<p>The <tt>dbType</tt> attribute is used to explicitly specify the database column
+type of the parameter to be set by this property. This attribute is normally
+only required if the column is nullable. Although, another reason to use the
+<tt>dbType</tt> attribute is to explicitly specify date types. Most SQL databases
+have more than one <tt>datetime</tt> type. Usually, a database has at least three
+different types (DATE, DATETIME, TIMESTAMP). In order for the value to map
+correctly, you might need to specify the column's <tt>dbType</tt>.</p>
+
+<div class="note"><b class="tip">Note:</b>
+Most providers only need the <tt>dbType</tt> specified for nullable columns. In
+this case, you only need to specify the type for the columns that are
+nullable.
+</div>
+
+<h2><tt>type</tt> attribute</h2>
+<p>The <tt>type</tt> attribute is used to specify the type of the parameter's
+property. This attribute is useful when passing <tt>InputOutput</tt> and
+<tt>Output</tt> parameters into stored procedures. The framework uses the
+specified type to properly handle and set the parameter object's properties
+with the procedure's output values after execution.</p>
+
+<h2><tt>nullValue</tt> attribute</h2>
+
+<p>The <tt>nullValue</tt> attribute can be set to any valid value (based on property
+type). The <tt>nullValue</tt> attribute is used to specify an outgoing null value
+replacement. What this means is that when the value is detected in the object
+property, a NULL will be written to the database (the opposite behavior of an
+inbound null value replacement). This allows you to use a magic null number in
+your application for types that do not support null values (such as int,
+double, float). When these types of properties contain a matching null value
+(for example, say, -9999), a NULL will be written to the database instead of
+the value.</p>
+
+<div class="tip"><b class="tip">Tip:</b>
+For round-trip transparency of null values, you must also specify database
+columns null value replacements in your <a href="?page=Manual.ResultMaps">Result Map</a>.
+</div>
+
+<h2><tt>size</tt> attribute</h2>
+<p>The <tt>size</tt> attribute sets the maximum size of the data within the column.</p>
+
+<h2><tt>precision</tt> attribute</h2>
+<p>The <tt>precision</tt> attribute is used to set the maximum number of digits used
+to represent the property value.</p>
+
+<h2><tt>scale</tt> attribute</h2>
+<p>The <tt>scale</tt> attribute sets the number of decimal places used to resolve the
+property value.</p>
+
+<h2><tt>typeHandler</tt> attribute</h2>
+<p>The <tt>typeHandler</tt> attribute allows the use of a
+<a href="?page=Manual.CustomTypeHandlers">Custom Type Handler</a>. This allows you to extend the DataMapper's
+capabilities in handling types that are specific to your database provider,
+are not handled by your database provider, or just happen to be a part of your
+application design. You can create custom type handlers to deal with storing
+and retrieving booleans from your database for example.</p>
+
+</com:TContent>
\ No newline at end of file |