db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1518685 - /db/derby/docs/branches/10.10/src/devguide/
Date Thu, 29 Aug 2013 16:09:49 GMT
Author: chaase3
Date: Thu Aug 29 16:09:48 2013
New Revision: 1518685

URL: http://svn.apache.org/r1518685
Log:
DERBY-4627  Document how to install your own custom collation for use in sorting and comparing
string data values.

Merged patch DERBY-4627.diff to 10.10 doc branch from trunk revision 1517620.

Added:
    db/derby/docs/branches/10.10/src/devguide/cdevcollationattribs.dita
      - copied unchanged from r1517620, db/derby/docs/trunk/src/devguide/cdevcollationattribs.dita
    db/derby/docs/branches/10.10/src/devguide/cdevcollationlikeequal.dita
      - copied unchanged from r1517620, db/derby/docs/trunk/src/devguide/cdevcollationlikeequal.dita
    db/derby/docs/branches/10.10/src/devguide/cdevcollationlocale.dita
      - copied unchanged from r1517620, db/derby/docs/trunk/src/devguide/cdevcollationlocale.dita
    db/derby/docs/branches/10.10/src/devguide/cdevcollationoverview.dita
      - copied unchanged from r1517620, db/derby/docs/trunk/src/devguide/cdevcollationoverview.dita
    db/derby/docs/branches/10.10/src/devguide/tdevdvlpcaseinscoll.dita
      - copied unchanged from r1517620, db/derby/docs/trunk/src/devguide/tdevdvlpcaseinscoll.dita
    db/derby/docs/branches/10.10/src/devguide/tdevdvlpcustomcollation.dita
      - copied unchanged from r1517620, db/derby/docs/trunk/src/devguide/tdevdvlpcustomcollation.dita
Modified:
    db/derby/docs/branches/10.10/src/devguide/cdevcollation.dita
    db/derby/docs/branches/10.10/src/devguide/derbydev.ditamap
    db/derby/docs/branches/10.10/src/devguide/tdevdvlpcollation.dita

Modified: db/derby/docs/branches/10.10/src/devguide/cdevcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/devguide/cdevcollation.dita?rev=1518685&r1=1518684&r2=1518685&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/devguide/cdevcollation.dita (original)
+++ db/derby/docs/branches/10.10/src/devguide/cdevcollation.dita Thu Aug 29 16:09:48 2013
@@ -23,169 +23,8 @@ limitations under the License.
 <ph conref="../conrefs.dita#prod/productshortname"></ph></title>
 <shortdesc>A character set is a set of symbols and encodings. Character data
 types are represented as Unicode 2.0 sequences in
-<ph conref="../conrefs.dita#prod/productshortname"></ph>. </shortdesc>
-<prolog><metadata>
-<keywords><indexterm>collation<indexterm>overview</indexterm></indexterm>
-<indexterm></indexterm></keywords>
-</metadata></prolog>
-<conbody>
-<section><title>How collation works in
-<ph conref="../conrefs.dita#prod/productshortname"></ph></title>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> supports a
wide
-range of character sets and encodes all of the character sets by using the
-Unicode support provided by the <i>java.lang.Character</i> class in the Java
-Virtual Machine (JVM) in which the
-<ph conref="../conrefs.dita#prod/productshortname"></ph> database runs. See the
-Java API documentation for the <i>java.lang.Character</i> class for
-the exact level of Unicode Standard that is supported.</p>
-<p>A collation is a set of rules for comparing characters in a character set.
-In <ph conref="../conrefs.dita#prod/productshortname"></ph>, the
-collation rules affect comparisons of the CHAR and VARCHAR data types. Collation
-rules also affect how the LIKE Boolean operator processes the CHAR, VARCHAR,
-CLOB, and LONG VARCHAR data types.</p>
-<p>The default <ph conref="../conrefs.dita#prod/productshortname"></ph>
-collation rule is based on the binary Unicode values of the characters. So a
-character is greater than (&gt;), equal to (=), or less than (&lt;) another
-character based on the numeric comparison of the Unicode values. This rule
-allows for very efficient comparisons of character strings.</p>
-<note>When LIKE comparisons
-are used, <ph conref="../conrefs.dita#prod/productshortname"></ph> compares
-one character at a time for non-metacharacters. This is different from the
-way <ph conref="../conrefs.dita#prod/productshortname"></ph>
-processes = comparisons.
-The comparisons with the = operator compare the entire character string on
-left side of the = operator with the entire character string on the right
-side of the = operator. See the
-<xref href="cdevcollation.dita#cdevcollation/territorylike"></xref> section
-below.</note></section>
-<section><title>Locale-based collation</title>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> also
-supports the ability to define collation rules that are appropriate to a
-locale. This is referred to as <i><term>locale-based collation</term></i>.
-<ph conref="../conrefs.dita#prod/productshortname"></ph> supports the locales
-that the Java programming language supports.</p>
-<p>You can specifically set the locale of a database when you create the
-database. (See
-<xref href="tdevdvlpcollation.dita#tdevdvlpcollation"></xref>
-for details.) If you do not specify a locale,
-<ph conref="../conrefs.dita#prod/productshortname"></ph> uses
-the default locale of the JVM in which the database is created. Each JVM
-can support many locales that are independent of the default locale
-for the JVM. Collation support for these additional locales is provided
-through the <i>java.text.RuleBasedCollator</i> class and the set
-of rules for these locales. Refer to the JVM specification for details
-of how these rules are used to provide locale-specific collation.
-<ph conref="../conrefs.dita#prod/productshortname"></ph> currently
-supports only running those rules that can be loaded dynamically from the
-running JVM based on the <i>territory=ll_CC</i> attribute. Overrides to these
-rules by the user are not supported.</p>
-<p>The locale-based collation in
-<ph conref="../conrefs.dita#prod/productshortname"></ph> affects
-how the CHAR and VARCHAR data types are compared. Specifying locale-based
-collation also impacts how the LIKE Boolean operator processes CHAR, VARCHAR,
-CLOB, and LONG VARCHAR data.</p>
-<p>Locale-based collation does add extra processing overhead to all
-character-based comparison operations.</p></section>
-<section><title>Database attributes that control collation</title>
-<p>When you create a <ph conref="../conrefs.dita#prod/productshortname"></ph>
-database, the attributes that you set determine the collation that is used with
-all character data in the database. The following table shows some examples.</p>
-<table>
-<title>The database creation attributes that control collation</title>
-<desc>This table shows how collation is controlled with various database creation attributes.</desc>
-<tgroup cols="2" colsep="1" rowsep="1">
-<colspec colname="col1" colnum="1" colwidth="70*"/>
-<colspec colname="col2" colnum="2" colwidth="30*"/>
-<thead>
-<row valign="bottom">
-<entry colname="col1">Example Create URLs</entry>
-<entry colname="col2">Collation Is Driven By</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry colname="col1">jdbc:derby:abcDB;create=true</entry>
-<entry colname="col2">Unicode codepoint collation (UCS_BASIC), which is the
-default collation for <ph conref="../conrefs.dita#prod/productshortname"></ph>
-databases.</entry>
-</row>
-<row>
-<entry colname="col1">jdbc:derby:abcDB;create=true;territory=es_MX</entry>
-<entry colname="col2">Unicode codepoint collation (UCS_BASIC). The
-<i>collation=collation</i> attribute is not set.</entry>
-</row>
-<row>
-<entry colname="col1">jdbc:derby:abcDB;create=true;collation=TERRITORY_BASED</entry>
-<entry colname="col2">The locale of the JVM, since the <i>territory=ll_CC</i>
-attribute is not set. <note type="tip">To determine the locale of the JVM,
-call the <i>Locale.getDefault</i>.</note></entry>
-</row>
-<row>
-<entry colname="col1">jdbc:derby:abcDB;create=true;territory=es_MX;collation=TERRITORY_BASED</entry>
-<entry colname="col2">The <i>territory=ll_CC</i> attribute.</entry>
-</row>
-</tbody>
-</tgroup>
-</table></section>
-<section><title>Collation examples</title><p>With Unicode codepoint
collation
-(UCS_BASIC), the numeric values of the Unicode encoding of the characters
-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>
-<sli>apple</sli>
-<sli>Banana</sli>
-<sli>Pineapple</sli>
-<sli>Grape</sli>
-</sl></p><p>UCS_BASIC collation sorts all lowercase letters before uppercase
-letters. The statement <codeph>SELECT * FROM FRUIT ORDER BY NAME</codeph>
-returns: <sl>
-<sli>apple</sli>
-<sli>orange</sli>
-<sli>Banana</sli>
-<sli>Grape</sli>
-<sli>Pineapple</sli>
-</sl></p><p>If the database is created with the <i>territory=ll_CC</i>
attribute
-set to <i>en_US</i> (English language, United States country code) and the
-<i>collation=collation</i> attribute set to TERRITORY_BASED, the statement
-<codeph>SELECT * FROM FRUIT ORDER BY NAME</codeph> returns: <sl>
-<sli>apple</sli>
-<sli>Banana</sli>
-<sli>Grape</sli>
-<sli>orange</sli>
-<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' ORDER BY NAME</codeph> returns: 
-<lines>      UCS_BASIC collation       Locale-based collation
-                Grape                             Grape
-                Pineapple                       orange
-                                                       Pineapple</lines></p>
-<p>For information on creating case-insensitive databases, see
-<xref href="tdevdvlpcollation.dita#tdevdvlpcollation/caseinsensitive"></xref>.</p>
-</section>
-<section id="territorylike"><title>Differences between LIKE and equal (=)
-comparisons</title><p>When you use locale-based collation, the comparisons
-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 locale where the character 'z' has the same collation elements as 'xy'. 
-Consider the following two WHERE clauses:</p>
-<ol>
-<li>WHERE 'zcb' = 'xycb'</li>
-<li>WHERE 'zcb' LIKE 'xy_b'</li>
-</ol>
-<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 2, <ph conref="../conrefs.dita#prod/productshortname"></ph>
-returns FALSE, because the collation element for the character 'z' does not
-match the collation element for the character 'x'. In addition, when a
-metacharacter such as an underscore is used with the LIKE operator, the
-metacharacter counts for one character in the string value. A clause such as
-<codeph>WHERE 'xycb' LIKE '_cb'</codeph> returns FALSE, because
-'x' is compared to the metacharacter '_' and 'y' does not match 'c'.</p>
-</section>
-</conbody>
+<ph conref="../conrefs.dita#prod/productshortname"></ph>. Collation defines how
+character data is sorted.</shortdesc>
+<conbody></conbody>
 </concept>
 

Modified: db/derby/docs/branches/10.10/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/devguide/derbydev.ditamap?rev=1518685&r1=1518684&r2=1518685&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/branches/10.10/src/devguide/derbydev.ditamap Thu Aug 29 16:09:48 2013
@@ -33,6 +33,79 @@ limitations under the License.
 <reltable>
 <relrow>
 <relcell>
+<topicref href="cdevcollation.dita" navtitle="Character-based collation in Derby"></topicref>
+</relcell>
+<relcell>
+<topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with locale-based
collation"></topicref>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database"></topicref>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="cdevcollationoverview.dita" navtitle="How collation works in Derby"></topicref>
+</relcell>
+<relcell>
+<topicref href="cdevcollationlocale.dita" navtitle="Locale-based collation"></topicref>
+<topicref href="cdevcollationattribs.dita" navtitle="Database connection URL attributes
that control collation"></topicref>
+<topicref href="cdevcollationlikeequal.dita" navtitle="Differences between LIKE and equal
(=) comparisons"></topicref>
+<topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with locale-based
collation"></topicref>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database"></topicref>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="cdevcollationlocale.dita" navtitle="Locale-based collation"></topicref>
+</relcell>
+<relcell>
+<topicref href="cdevcollationattribs.dita" navtitle="Database connection URL attributes
that control collation"></topicref>
+<topicref href="cdevcollationlikeequal.dita" navtitle="Differences between LIKE and equal
(=) comparisons"></topicref>
+<topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with locale-based
collation"></topicref>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database"></topicref>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="cdevcollationattribs.dita" navtitle="Database connection URL attributes
that control collation"></topicref>
+</relcell>
+<relcell>
+<topicref href="cdevcollationlikeequal.dita" navtitle="Differences between LIKE and equal
(=) comparisons"></topicref>
+<topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with locale-based
collation"></topicref>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database"></topicref>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="cdevcollationlikeequal.dita" navtitle="Differences between LIKE and equal
(=) comparisons"></topicref>
+</relcell>
+<relcell>
+<topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with locale-based
collation"></topicref>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database"></topicref>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database"></topicref>
+</relcell>
+<relcell>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with locale-based
collation"></topicref>
+</relcell>
+<relcell>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database"></topicref>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
 <topicref href="tdevpreupgrade.dita" navtitle="Preparing to upgrade"></topicref>
 </relcell>
 <relcell>
@@ -1465,13 +1538,23 @@ limitations under the License.
 </topicref>
 </relcell>
 <relcell>
-<topicref href="cdevin55108.dita" navtitle="Other components"></topicref>
+<topicref href="cdevcollation.dita" navtitle="Character-based collation in Derby"></topicref>
+<topicref href="cdevin55108.dita" navtitle="Other components with locale support"></topicref>
 <topicref href="cdevin38113.dita" navtitle="Messages libraries"></topicref>
 </relcell>
 </relrow>
 <relrow>
 <relcell>
-<topicref href="cdevin55108.dita" navtitle="Other components"></topicref>
+<topicref href="cdevcollation.dita" navtitle="Character-based collation in Derby"></topicref>
+</relcell>
+<relcell>
+<topicref href="cdevin55108.dita" navtitle="Other components with locale support"></topicref>
+<topicref href="cdevin38113.dita" navtitle="Messages libraries"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="cdevin55108.dita" navtitle="Other components with locale support"></topicref>
 </relcell>
 <relcell>
 <topicref href="cdevin38113.dita" navtitle="Messages libraries"></topicref>
@@ -1580,6 +1663,10 @@ limitations under the License.
 </topicref>
 <topicref href="tdevdvlpcollation.dita" navtitle="Creating a database with locale-based
collation">
 </topicref>
+<topicref href="tdevdvlpcaseinscoll.dita" navtitle="Creating a case-insensitive database">
+</topicref>
+<topicref href="tdevdvlpcustomcollation.dita" navtitle="Creating a customized collator">
+</topicref>
 <topicref href="tdevdvlp36289.dita" navtitle="Specifying attributes in a properties object">
 </topicref>
 </topicref>
@@ -1969,7 +2056,15 @@ with updatable result sets"></topicref>
 <topicref href="cdevin10613.dita" navtitle="Localizing Derby">
 <topicref href="cdevin71274.dita" navtitle="SQL parser support for Unicode">
 </topicref>
-<topicref href="cdevcollation.dita" navtitle="Character-based collation in  Derby">
+<topicref href="cdevcollation.dita" navtitle="Character-based collation in Derby">
+<topicref href="cdevcollationoverview.dita" navtitle="How collation works in Derby">
+</topicref>
+<topicref href="cdevcollationlocale.dita" navtitle="Locale-based collation">
+</topicref>
+<topicref href="cdevcollationattribs.dita" navtitle="Database connection URL attributes
that control collation">
+</topicref>
+<topicref href="cdevcollationlikeequal.dita" navtitle="Differences between LIKE and equal
(=) comparisons">
+</topicref>
 </topicref>
 <topicref href="cdevin55108.dita" navtitle="Other components"></topicref>
 <topicref href="cdevin38113.dita" navtitle="Messages libraries"></topicref>

Modified: db/derby/docs/branches/10.10/src/devguide/tdevdvlpcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.10/src/devguide/tdevdvlpcollation.dita?rev=1518685&r1=1518684&r2=1518685&view=diff
==============================================================================
--- db/derby/docs/branches/10.10/src/devguide/tdevdvlpcollation.dita (original)
+++ db/derby/docs/branches/10.10/src/devguide/tdevdvlpcollation.dita Thu Aug 29 16:09:48 2013
@@ -36,34 +36,19 @@ to user-defined tables. The system table
 type="restriction">The <i>collation=collation</i> and
 <i>territory=ll_CC</i> attributes can be specified
 only when you create a database. You cannot specify these attributes on an existing
-database or when you upgrade a database.</note><p>To create a database with
-locale-based collation:</p></context>
-<steps>
-<step><cmd>Specify the language and country codes for the <i>territory=ll_CC</i>
-attribute, and the TERRITORY_BASED value for the <i>collation=collation</i>
-attribute, 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 id="caseinsensitive"><title>Creating a case-insensitive database</title>
-<p>The <i>collation=collation</i> 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
-<i>collation=collation</i> 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 '&#224;' ('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 <i>collation=collation</i> attribute in the
-<ph conref="../conrefs.dita#pub/citref"></ph>.</p>
-</example>
+database or when you upgrade a database.</note>
+<p>To create a database with locale-based collation, specify the
+language and country codes for the <i>territory=ll_CC</i> attribute, and the
+TERRITORY_BASED value for the <i>collation=collation</i> attribute, when you
+create the database.</p>
+<p>For example, you could use the following connection URL:</p>
+<codeblock>jdbc:derby:MexicanDB;create=true;territory=es_MX;collation=TERRITORY_BASED
+</codeblock>
+<p>See the documentation of the <i>territory=ll_CC</i> and
+<i>collation=collation</i> attributes in the
+<ph conref="../conrefs.dita#pub/citref"></ph> for details on these attributes.
+See <xref href="tdevdvlpcaseinscoll.dita#tdevdvlpcaseinscoll"></xref> for
+information on making the database use case-insensensitive searches.</p>
+</context>
 </taskbody>
 </task>



Mime
View raw message