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 2013/08/26 19:48:02 UTC
svn commit: r1517620 - /db/derby/docs/trunk/src/devguide/
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 (>), equal to (=), or less than (<) 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 (>), equal to (=), or less than (<) 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 'à' ('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 'à' ('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 ('α' near 'a', ''β' 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 < b,B < 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("< a,A < \u03b1,\u0391 < b,B");
+ // beta should go between b and c
+ rules.append("& b,B < \u03b2,\u0392 < 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', 'α', 'β';
+5 rows inserted/updated/deleted
+ij> select * from t order by x;
+X
+------------
+a
+α
+b
+β
+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