You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ch...@apache.org on 2010/04/08 21:13:00 UTC
svn commit: r932066 - in /db/derby/docs/trunk/src:
devguide/cdevcollation.dita devguide/tdevdvlpcollation.dita
ref/rrefattribcollation.dita
Author: chaase3
Date: Thu Apr 8 19:12:59 2010
New Revision: 932066
URL: http://svn.apache.org/viewvc?rev=932066&view=rev
Log:
DERBY-4591: Documentation needed for global case-insensitive setting (DERBY-1748)
Modified 2 topics in Dev Guide and one in Ref Manual.
Patch: DERBY-4591.diff
Modified:
db/derby/docs/trunk/src/devguide/cdevcollation.dita
db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita
db/derby/docs/trunk/src/ref/rrefattribcollation.dita
Modified: db/derby/docs/trunk/src/devguide/cdevcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcollation.dita?rev=932066&r1=932065&r2=932066&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcollation.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcollation.dita Thu Apr 8 19:12:59 2010
@@ -105,7 +105,7 @@ is not set. <note type="tip">To determin
</table></p></section>
<section><title>Collation examples</title><p>With Unicode codepoint collation
(UCS_BASIC), the numerical values of the Unicode encoding of the characters
-is used directly for ordering. For example, the FRUIT table contains the NAME
+are used directly for ordering. For example, the FRUIT table contains the NAME
column that uses the VARCHAR(20) data type. The contents of the NAME column
are:<sl>
<sli>orange</sli>
@@ -122,7 +122,7 @@ case letters. The statement <codeph>SELE
<sli>Pineapple</sli>
</sl></p><p>If the database is created with the territory attribute set to
en_US (English language, United States country code), and the collation attribute
-set to TERRITORY_BASED , the results of the statement <codeph>SELECT * FROM
+set to TERRITORY_BASED, the results of the statement <codeph>SELECT * FROM
FRUIT ORDER BY NAME</codeph> returns: <sl>
<sli>apple</sli>
<sli>Banana</sli>
@@ -131,18 +131,22 @@ FRUIT ORDER BY NAME</codeph> returns: <s
<sli>Pineapple</sli>
</sl></p><p>The collation set for the database also impacts comparison operators
on character data types. For example, the statement <codeph>SELECT * FROM
-FRUIT WHERE NAME > Banana</codeph> returns: <lines> UCS_BASIC collation Territory-based collation
+FRUIT WHERE NAME > 'Banana' ORDER BY NAME</codeph> returns:
+<lines> UCS_BASIC collation Territory-based collation
Grape Grape
Pineapple orange
- Pineapple</lines></p> </section>
+ Pineapple</lines></p>
+<p>For information on creating case-insensitive databases, see
+<xref href="tdevdvlpcollation.dita#tdevdvlpcollation"></xref>.</p>
+</section>
<section id="territorylike"><title>Differences between LIKE and equal (=)
comparisons</title><p>When you use territory-based collation, the comparisons
-can <?Pub Caret?>return different results when you use the LIKE and equal
+can return different results when you use the LIKE and equal
(=) operators. For example, suppose that the <ph conref="../conrefs.dita#prod/productshortname"></ph> database
is set to use a territory where the character 'z' has same collation elements
as 'xy'. Consider the following two WHERE clauses: <ol>
<li>WHERE 'zcb' = 'xycb'</li>
-<li>WHERE 'zcb' LIKE 'xy_b</li>
+<li>WHERE 'zcb' LIKE 'xy_b'</li>
</ol></p><p>For WHERE clause 1, <ph conref="../conrefs.dita#prod/productshortname"></ph> returns
TRUE because the collation elements for the entire string 'zcb' will match
the collation elements of the entire string 'xycb'. </p><p>For WHERE clause
Modified: db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita?rev=932066&r1=932065&r2=932066&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita Thu Apr 8 19:12:59 2010
@@ -28,7 +28,7 @@ when you create the database.</shortdesc
<indexterm>collation <indexterm>territory-based</indexterm></indexterm></keywords>
</metadata></prolog>
<taskbody>
-<context>.<p>You can use the <codeph>collation</codeph> and <codeph>territory</codeph> attributes
+<context><p>You can use the <codeph>collation</codeph> and <codeph>territory</codeph> attributes
to specify territory-based collation. This type of collation applies only
to user-defined tables. The system tables use the Unicode codepoint collation. </p><note
type="restriction">The <codeph>collation</codeph> attribute can be specified
@@ -41,5 +41,25 @@ and the TERRITORY_BASED value for the <c
when you create the database.</cmd><stepxmp><p>For example:</p><codeblock>jdbc:derby:MexicanDB;create=true;territory=es_MX;collation=TERRITORY_BASED </codeblock
></stepxmp></step>
</steps>
+<example><title>Creating a case-insensitive database</title>
+<p>The <codeph>collation</codeph> value TERRITORY_BASED uses the default
+collation strength for the locale, usually TERTIARY, which will consider
+character case significant in searches and comparisons. To make the database
+use case-insensitive searches, specify an explicit strength with the
+<codeph>collation</codeph> attribute. The strength name is appended to
+TERRITORY_BASED with a colon to separate them.</p>
+<p>For example:</p>
+<codeblock>jdbc:derby:SwedishDB;create=true;territory=sv_SE;collation=TERRITORY_BASED:PRIMARY</codeblock>
+<p>With strength PRIMARY, the characters 'A' and 'a' will be considered equal,
+as well as 'a' with no accent and 'a' with a grave accent. (This behavior is
+commonly the default with many other databases.) To make searches
+respect differences in accent, use strength SECONDARY.</p>
+<p>The exact interpretation of the strength part of the attribute depends upon
+the locale.</p>
+<p>For more information, see
+<xref href="cdevcollation.dita#cdevcollation"></xref> and the documentation of
+the <codeph>collation</codeph> attribute in the
+<ph conref="../conrefs.dita#pub/citref"></ph>.</p>
+</example>
</taskbody>
</task>
Modified: db/derby/docs/trunk/src/ref/rrefattribcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribcollation.dita?rev=932066&r1=932065&r2=932066&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattribcollation.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefattribcollation.dita Thu Apr 8 19:12:59 2010
@@ -30,27 +30,61 @@ limitations under the License.
<section><title>Function</title><p>The <codeph>collation</codeph> attribute
is an optional attribute that specifies whether collation is based on the
territory specified for the database or Unicode codepoint collation. The valid
-values for the <codeph>collation</codeph> attribute are: TERRITORY_BASED and
-UCS_BASIC. The default collation is Unicode codepoint collation (UCS_BASIC).</p><note
+values for the <codeph>collation</codeph> attribute are:</p>
+<dl>
+<dlentry>
+<dt>UCS_BASIC</dt>
+<dd>Unicode codepoint collation. This value is the default.</dd>
+</dlentry>
+<dlentry>
+<dt>TERRITORY_BASED</dt>
+<dd>Based on the language specified with the territory attribute. The default
+collation strength for the locale is used. The default for
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is commonly TERTIARY,
+in which character case is significant in searches and comparisons.</dd>
+</dlentry>
+<dlentry>
+<dt>TERRITORY_BASED:PRIMARY</dt>
+<dd>Territory based with collation strength PRIMARY. Specify this value to make
+<ph conref="../conrefs.dita#prod/productshortname"></ph> behave similarly to
+many other databases, for which PRIMARY is commonly the default.</dd>
+</dlentry>
+<dlentry>
+<dt>TERRITORY_BASED:SECONDARY</dt>
+<dd>Territory based with collation strength SECONDARY.</dd>
+</dlentry>
+<dlentry>
+<dt>TERRITORY_BASED:TERTIARY</dt>
+<dd>Territory based with collation strength TERTIARY.</dd>
+</dlentry>
+<dlentry>
+<dt>TERRITORY_BASED:IDENTICAL</dt>
+<dd>Territory based with collation strength IDENTICAL.</dd>
+</dlentry>
+</dl>
+<note
type="restriction">The <codeph>collation</codeph> attribute can be specified
only when you create a database. You cannot specify this attribute on an existing
-database or when you upgrade a database.</note><p>If you include the <codeph>collation</codeph> attribute
-with the value TERRITORY_BASED when you create the <ph conref="../conrefs.dita#prod/productshortname"></ph> database,
-the collation is based on the language and country codes that you specify
+database or when you upgrade a database.</note>
+<p>If you specify the <codeph>collation</codeph> attribute with the value
+TERRITORY_BASED, or one of its variants with a specific collation strength, the
+collation is based on the language and country codes that you specify
with the <codeph>territory</codeph> attribute.</p><p>If you do not specify
the <codeph>territory</codeph> attribute when you create the database, <ph
conref="../conrefs.dita#prod/productshortname"></ph> uses the <codeph>java.util.Locale.getDefault</codeph> method
to determine the current value of the default locale for this instance of
the Java Virtual Machine (JVM).</p><note>The <codeph>collation</codeph> attribute
applies only to user-defined tables. The system tables use the Unicode codepoint
-collation.</note></section>
+collation.</note>
+<p>For information on how
+<ph conref="../conrefs.dita#prod/productshortname"></ph> handles collation, see
+"Creating a database with territory-based collation" and "Character-based
+collation in <ph conref="../conrefs.dita#prod/productshortname"></ph>" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p></section>
<example><title>Example</title><p>The following example shows the URL to create
the <codeph>MexicanDB</codeph> database. The territory attribute specifies
Spanish for the language code and Mexico for the country code. The <codeph>collation</codeph> attribute
specifies that the collation for the database is territory based.</p><codeblock>jdbc:derby:MexicanDB;create=true;territory=es_MX;collation=TERRITORY_BASED </codeblock
> </example>
-<section><title></title>For information on how <ph conref="../conrefs.dita#prod/productshortname"></ph> handles
-collation, see "Character-based collation in <ph conref="../conrefs.dita#prod/productshortname"></ph>"
-in the <cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite></section>
</refbody>
</reference>