db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1517620 - /db/derby/docs/trunk/src/devguide/
Date Mon, 26 Aug 2013 17:48:02 GMT
Author: chaase3
Date: Mon Aug 26 17:48:02 2013
New Revision: 1517620

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

Modified 2 Developer's Guide topics and added 6, breaking the original topics up to make the content more visible and adding another one on installing your own custom collation.

Patch: DERBY-4627.diff

Added:
    db/derby/docs/trunk/src/devguide/cdevcollationattribs.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevcollationlikeequal.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevcollationlocale.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevcollationoverview.dita   (with props)
    db/derby/docs/trunk/src/devguide/tdevdvlpcaseinscoll.dita   (with props)
    db/derby/docs/trunk/src/devguide/tdevdvlpcustomcollation.dita   (with props)
Modified:
    db/derby/docs/trunk/src/devguide/cdevcollation.dita
    db/derby/docs/trunk/src/devguide/derbydev.ditamap
    db/derby/docs/trunk/src/devguide/tdevdvlpcollation.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=1517620&r1=1517619&r2=1517620&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcollation.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcollation.dita Mon Aug 26 17:48:02 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>
 

Added: db/derby/docs/trunk/src/devguide/cdevcollationattribs.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcollationattribs.dita?rev=1517620&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcollationattribs.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcollationattribs.dita Mon Aug 26 17:48:02 2013
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevcollationattribs" xml:lang="en-us">
+<title>Database connection URL attributes that control collation</title>
+<shortdesc>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.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>collation<indexterm>connection URL attributes</indexterm></indexterm>
+<indexterm>locale-based collation<indexterm>connection URL attributes</indexterm></indexterm>
+<indexterm>connection URL attributes<indexterm>locale-based collation</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<section><p>The following table shows some examples.</p>
+<table>
+<title>Database creation URL attributes that control collation</title>
+<desc>This table shows how collation is controlled with various database creation URL 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>
+<row>
+<entry colname="col1">jdbc:derby:abcDB;create=true;territory=es_MX;collation=TERRITORY_BASED:PRIMARY</entry>
+<entry colname="col2">The <i>territory=ll_CC</i> attribute with collation
+strength PRIMARY, which makes the database case-insensitive (it typically means
+that only differences in base letters are considered significant).</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 uppercase letters before lowercase
+letters. The statement <codeph>SELECT * FROM FRUIT ORDER BY NAME</codeph>
+returns the following: <sl>
+<sli>Banana</sli>
+<sli>Grape</sli>
+<sli>Pineapple</sli>
+<sli>apple</sli>
+<sli>orange</sli>
+</sl></p>
+<p>The above result also appears if you specify <i>territory=ll_CC</i> but do
+not specify <i>collation=collation</i>.</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
+                apple                              Pineapple
+                orange</lines></p>
+<p>For information on creating case-insensitive databases, see
+<xref href="tdevdvlpcaseinscoll.dita#tdevdvlpcaseinscoll"></xref>.</p>
+</section>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevcollationattribs.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevcollationlikeequal.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcollationlikeequal.dita?rev=1517620&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcollationlikeequal.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcollationlikeequal.dita Mon Aug 26 17:48:02 2013
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevcollationlikeequal" xml:lang="en-us">
+<title>Differences between LIKE and equal (=) comparisons</title>
+<shortdesc>When you use locale-based collation, the comparisons
+can return different results when you use the LIKE and equal
+(=) operators.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>collation<indexterm>LIKE and equal (=) comparisons</indexterm></indexterm>
+<indexterm>LIKE comparisons<indexterm>collation and</indexterm></indexterm>
+<indexterm>equal (=) comparisons<indexterm>collation and</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<section>
+<p>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>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevcollationlikeequal.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevcollationlocale.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcollationlocale.dita?rev=1517620&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcollationlocale.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcollationlocale.dita Mon Aug 26 17:48:02 2013
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevcollationlocale" xml:lang="en-us">
+<title>Locale-based collation</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph>
+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>.
+</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>collation<indexterm>locale-based</indexterm></indexterm>
+<indexterm>locale-based collation</indexterm></keywords>
+</metadata></prolog>
+<conbody>
+<section>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> supports the locales
+that the Java programming language supports. In addition, it is possible to
+create customized locales. For details, see
+<xref href="tdevdvlpcustomcollation.dita#tdevdvlpcustomcollation"></xref>.</p>
+<p>You can set the locale of a database when you create the database by
+specifying the <i>territory=ll_CC</i> attribute. (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.</p>
+<p>At the same time, you can also specify locale-based collation by using the
+<i>collation=collation</i> attribute, and you can specify a particular
+collation strength to make the database either case-sensitive or
+case-insensitive, or to respect both case and accent in collation. See
+<xref href="tdevdvlpcaseinscoll.dita#tdevdvlpcaseinscoll"></xref> for
+information on making the database use case-insensensitive searches.</p>
+<p>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.</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 adds some extra processing overhead to all
+character-based comparison operations.</p>
+</section>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevcollationlocale.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevcollationoverview.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcollationoverview.dita?rev=1517620&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcollationoverview.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcollationoverview.dita Mon Aug 26 17:48:02 2013
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="cdevcollationoverview" xml:lang="en-us">
+<title>How collation works in
+<ph conref="../conrefs.dita#prod/productshortname"></ph></title>
+<shortdesc><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.
+</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>collation<indexterm>overview</indexterm></indexterm>
+<indexterm></indexterm></keywords>
+</metadata></prolog>
+<conbody>
+<section>
+<p>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 the left side of the = operator with the entire character string on
+the right side of the = operator. For details, see
+<xref href="cdevcollationlikeequal.dita#cdevcollationlikeequal"></xref>.</note>
+</section>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevcollationoverview.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=1517620&r1=1517619&r2=1517620&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Mon Aug 26 17:48:02 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>

Added: db/derby/docs/trunk/src/devguide/tdevdvlpcaseinscoll.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlpcaseinscoll.dita?rev=1517620&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlpcaseinscoll.dita (added)
+++ db/derby/docs/trunk/src/devguide/tdevdvlpcaseinscoll.dita Mon Aug 26 17:48:02 2013
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "../dtd/task.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<task id="tdevdvlpcaseinscoll" xml:lang="en-us">
+<title>Creating a case-insensitive database</title>
+<shortdesc>When you create a database using locale-based collation, 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.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>database attributes <indexterm>case-insensitive collation</indexterm></indexterm>
+<indexterm>collation <indexterm>case-insensitive</indexterm></indexterm></keywords>
+</metadata></prolog>
+<taskbody>
+<context><p>To make the database use case-insensitive searches, specify an
+explicit strength lower than TERTIARY 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, you could specify the following connection URL:</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="tdevdvlpcollation.dita#tdevdvlpcollation"></xref> and the
+documentation of the <i>territory=ll_CC</i> and <i>collation=collation</i>
+attributes in the <ph conref="../conrefs.dita#pub/citref"></ph>.</p>
+</context>
+</taskbody>
+</task>

Propchange: db/derby/docs/trunk/src/devguide/tdevdvlpcaseinscoll.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita?rev=1517620&r1=1517619&r2=1517620&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevdvlpcollation.dita Mon Aug 26 17:48:02 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>

Added: db/derby/docs/trunk/src/devguide/tdevdvlpcustomcollation.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlpcustomcollation.dita?rev=1517620&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlpcustomcollation.dita (added)
+++ db/derby/docs/trunk/src/devguide/tdevdvlpcustomcollation.dita Mon Aug 26 17:48:02 2013
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "../dtd/task.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<task id="tdevdvlpcustomcollation" xml:lang="en-us">
+<title>Creating a customized collator</title>
+<shortdesc>You may need to define a collation order different from that of the
+strengths provided by the <i>collation=collation</i> attribute.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>customizing collation</indexterm>
+<indexterm>collation <indexterm>customized</indexterm></indexterm></keywords>
+</metadata></prolog>
+<taskbody>
+<context>
+<p>To define a new collation order, follow these steps.</p>
+</context>
+<steps>
+<step>
+<cmd>Create a class that extends the <i>java.text.spi.CollatorProvider</i>
+class and that returns a collator that orders strings the way you want it
+to.</cmd>
+</step>
+<step>
+<cmd>Create a text file named
+<i>META-INF/services/java.text.spi.CollatorProvider</i> that contains one line
+with the name of your collator provider class.</cmd>
+</step>
+<step>
+<cmd>Put the compiled class file and the text file in a jar file that you drop
+into your JRE's <i>lib/ext</i> directory or in one of the directories specified
+by the <i>java.ext.dirs</i> property.</cmd></step>
+</steps>
+<example>
+<p>For example, suppose you want to define a collation order to make Greek
+characters sort near their Latin equivalents ('&#945;' near 'a', ''&#946;' near
+'b', and so on). You could define another locale with a <i>CollatorProvider</i>
+that returns a <i>java.text.RuleBasedCollator</i> with  ever rules you want.
+See the API documentation for the <i>RuleBasedCollator</i> class for details
+about how you specify rules. In its simplest form, a set of rules might look
+like <codeph>"a,A &lt; b,B &lt; c,C"</codeph>, which means more or less that
+'a' and 'A' should be sorted before 'b' and 'B', which should be sorted before
+'c' and 'C'. So to get the Greek characters sorted near similar Latin
+characters, define a <i>CollatorProvider</i> that looks like this one:</p>
+<codeblock>
+public class MyCollatorProvider extends CollatorProvider {
+    public Locale[] getAvailableLocales() {
+        return new Locale[] {
+            new Locale("en", "US", "greek")
+        };
+    }
+    
+    public Collator getInstance(Locale locale) {
+        StringBuilder rules = new StringBuilder();
+        // alpha should go between a and b
+        rules.append("&lt; a,A &lt; \u03b1,\u0391 &lt; b,B");
+        // beta should go between b and c
+        rules.append("&amp; b,B &lt; \u03b2,\u0392 &lt; c,C");
+        // add more rules here ....
+
+        try {
+            return new RuleBasedCollator(rules.toString());
+        } catch (ParseException pe) {
+            throw new Error(pe);
+        }
+    }
+}
+</codeblock>
+<p>Again, put the compiled class and the
+<i>META-INF/services/java.text.spi.CollatorProvider</i> file in a jar file, and
+start the <codeph>ij</codeph> tool with the <codeph>-Djava.ext.dirs=.</codeph>
+option in the directory where the jar file is located. Create a database that
+uses the new locale and insert some data with both Greek and Latin
+characters:</p>
+<codeblock>
+ij> connect 'jdbc:derby:GreekDB;territory=en_US_greek;collation=TERRITORY_BASED;create=true';
+ij> create table t (x varchar(12));
+0 rows inserted/updated/deleted
+ij> insert into t values 'a', 'b', 'c', '&#945;', '&#946;';
+5 rows inserted/updated/deleted
+ij> select * from t order by x;
+X           
+------------
+a
+&#945;
+b
+&#946;
+c 
+
+5 rows selected
+</codeblock>
+<p>The ordering is just as you wanted it, with the Greek characters between the
+Latin ones, and not at the end where they would normally be located.</p>
+<p>One word of caution: If, after you have created a database, you update your
+custom <i>CollatorProvider</i> so that the ordering is changed, you will need
+to recreate the database. You must do this because the indexes in the database
+are ordered, and you may see strange results if the indexes are ordered with a
+different collator from the one your database is currently using.</p>
+</example>
+</taskbody>
+</task>

Propchange: db/derby/docs/trunk/src/devguide/tdevdvlpcustomcollation.dita
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message