[DOCUMENTATION] Japanese sync 19577, 19674, 19692, 19738

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@19741 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/ja/manual.xml.in

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
-<!-- EN-Revision: 19728 -->
+<!-- EN-Revision: 19738 -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
     "@DOCBOOK_DTD@"
 [
@@ -603,6 +603,17 @@
         <xi:include href="module_specs/Zend_TimeSync-Working.xml" />
     </chapter>
 
+    <chapter id="zend.tool">
+        <title>Zend_Tool</title>
+        <xi:include href="module_specs/Zend_Tool-Usage-CLI.xml">
+            <xi:fallback><xi:include href="../en/module_specs/Zend_Tool-Usage-CLI.xml" /></xi:fallback>
+        </xi:include>
+        <xi:include href="module_specs/Zend_Tool-Extending.xml">
+            <xi:fallback><xi:include href="../en/module_specs/Zend_Tool-Extending.xml" /></xi:fallback>
+        </xi:include>
+    </chapter>
+
+    <!--
     <chapter id="zend.tool.framework">
         <title>Zend_Tool_Framework</title>
         <xi:include href="module_specs/Zend_Tool_Framework-Introduction.xml" />
@@ -620,8 +631,9 @@
         <xi:include href="module_specs/Zend_Tool_Project.xml" />
         <xi:include href="module_specs/Zend_Tool_Project-CreateProject.xml" />
         <xi:include href="module_specs/Zend_Tool_Project-Providers.xml" />
-        <!-- <xi:include href="module_specs/Zend_Tool_Project-Internals.xml" /> -->
+        <xi:include href="module_specs/Zend_Tool_Project-Internals.xml" />
     </chapter>
+    -->
 
     <chapter id="zend.translate">
         <title>Zend_Translate</title>

documentation/manual/ja/module_specs/Zend_Validate-Set.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
-<!-- EN-Revision: 18986 -->
+<!-- EN-Revision: 19692 -->
 <sect1 id="zend.validate.set" xmlns:xi="http://www.w3.org/2001/XInclude">
 
     <title>標準のバリデーションクラス群</title>
@@ -34,18 +34,9 @@
         </para>
     </sect2>
 
-    <sect2 id="zend.validate.set.barcode">
-        <title>Barcode</title>
-        <para>
-            このバリデータのインスタンスを作成する際には、検証したいバーコードの形式を指定します。
-            現在サポートしているバーコード形式は "<code>UPC-A</code>" (Universal Product Code) と
-            "<code>EAN-13</code>" (European Article Number) です。
-            <methodname>isValid()</methodname> メソッドは、
-            指定した型のバーコードの検証アルゴリズムで入力が検証できた場合に
-            true を返します。このバリデータに入力を渡す前に、
-            数字の 0 から 9 まで (0-9) 以外の文字はすべて取り除いておかなければなりません。
-        </para>
-    </sect2>
+    <xi:include href="Zend_Validate-Barcode.xml">
+        <xi:fallback><xi:include href="../../en/module_specs/Zend_Validate-Barcode.xml" /></xi:fallback>
+    </xi:include>
 
     <sect2 id="zend.validate.set.between">
         <title>Between</title>
@@ -84,10 +75,10 @@
     <sect2 id="zend.validate.set.date">
         <title>Date</title>
         <para>
-            <code>$value</code> が <code>YYYY-MM-DD</code> 形式の日付である場合にのみ
-            <constant>TRUE</constant> を返します。オプションの <code>locale</code>
+            <code>$value</code> が 'YYYY-MM-DD' 形式の日付である場合にのみ
+            <constant>TRUE</constant> を返します。オプションの <property>locale</property>
             を設定すると、そのロケールに応じた検証を行います。
-            オプションの <code>format</code> を設定すると、
+            オプションの <property>format</property> を設定すると、
             そのフォーマットを使用して検証を行います。オプションパラメータの詳細は
             <link linkend="zend.date.others.comparison.table">Zend_Date::isDate()</link>
             を参照ください。
@@ -234,8 +225,8 @@ if ($validator->isValid($iban)) {
             <methodname>setMin()</methodname>
             で最大値より大きい値を指定したり <methodname>setMax()</methodname>
             で最小値より小さい値を設定したりした場合に例外をスローします。
-            このクラスは UTF-8 のほかに
-            <ulink url="http://www.php.net/manual/ja/ref.iconv.php#iconv.configuration"><code>iconv.internal_encoding</code></ulink>
+            このクラスは UTF-8 のほかに <ulink
+                url="http://www.php.net/manual/ja/ref.iconv.php#iconv.configuration">iconv.internal_encoding</ulink>
             にもとづいたその他の文字エンコーディングもサポートします。
             別のエンコーディングを使用したい場合は、アクセサメソッド getEncoding
             および setEncoding で設定します。

documentation/manual/ja/module_specs/Zend_Validate-WritingValidators.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
-<!-- EN-Revision: 18032 -->
+<!-- EN-Revision: 19577 -->
 <sect1 id="zend.validate.writing_validators">
 
     <title>バリデータの書き方</title>
@@ -18,7 +18,7 @@
         独自のバリデーションオブジェクトを作成します。
         <classname>Zend_Validate_Interface</classname> を実装したクラスは、
         <methodname>Zend_Validate::addValidator()</methodname>
-        でバリデータチェインに追加することができます。
+        でバリデータチェインに追加できます。
         このオブジェクトは
         <link linkend="zend.filter.input"><classname>Zend_Filter_Input</classname></link>
         でも使用します。
@@ -85,7 +85,7 @@ class MyValid_Float extends Zend_Validate_Abstract
 
         <para>
             このクラス内には、検証が失敗したときのメッセージ用のテンプレートがひとつ定義されており、
-            その中では組み込みのマジックパラメータ <code>%value%</code> を使用しています。
+            その中では組み込みのマジックパラメータ <emphasis>%value%</emphasis> を使用しています。
             <methodname>_setValue()</methodname> のコールによって、検証した値をこのメッセージに自動的に格納します。
             これにより、検証に失敗したときに、この値をメッセージに含められるようになります。
             <methodname>_error()</methodname> のコールによって、検証に失敗した原因を取得します。
@@ -170,8 +170,8 @@ class MyValid_NumericBetween extends Zend_Validate_Abstract
             パブリックプロパティ <code>$minimum</code> および <code>$maximum</code>
             でそれぞれ最小値と最大値を定義し、値がこの間にあった場合に検証が成功したことにしています。
             このクラスではまた、それぞれのパブリックプロパティに対応するふたつのメッセージ変数を定義しています。
-            そしてメッセージテンプレートの中で <code>value</code> と同様に使えるマジックパラメータとして
-            <code>min</code> および <code>max</code> も用意しています。
+            そしてメッセージテンプレートの中で <property>value</property> と同様に使えるマジックパラメータとして
+            <property>min</property> および <property>max</property> も用意しています。
         </para>
 
         <para>
@@ -267,7 +267,7 @@ class MyValid_PasswordStrength extends Zend_Validate_Abstract
             チェックに失敗してもその場では <constant>FALSE</constant> を返していないことに注目しましょう。
             これにより、入力されたパスワードが満たしていない条件を <emphasis>すべて</emphasis>
             示すことができるようになります。たとえば、パスワードとして入力された値が
-            "<code>#$%</code>" だったとすると、<methodname>isValid()</methodname>
+            "#$%" だったとすると、<methodname>isValid()</methodname>
             は四つのメッセージをすべて作成し、後で <methodname>getMessages()</methodname>
             をコールした際にすべて取得できるようになります。
         </para>

documentation/manual/ja/module_specs/Zend_XmlRpc_Server.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
-<!-- EN-Revision: 17520 -->
+<!-- EN-Revision: 19674 -->
 <sect1 id="zend.xmlrpc.server">
     <title>Zend_XmlRpc_Server</title>
 
@@ -61,10 +61,61 @@ echo $server->handle();
             <classname>Zend_XmlRpc_Response</classname> を継承したオブジェクトか
             <classname>Zend_XmlRpc_Server_Fault</classname> オブジェクトを返します。
             これらのオブジェクトはどちらも <methodname>__toString()</methodname>
-            メソッドを実装しており、妥当な <acronym>XML-RPC</acronym> <acronym>XML</acronym> レスポンスを直接出力することができます。
+            メソッドを実装しており、妥当な <acronym>XML-RPC</acronym> <acronym>XML</acronym> レスポンスを直接出力できます。
         </para>
     </sect2>
 
+    <!-- TODO : to be translated -->
+    <sect2 id="zend.xmlrpc.server.anatomy">
+        <title>Anatomy of a webservice</title>
+
+        <sect3 id="zend.xmlrpc.server.anatomy.general">
+            <title>General considerations</title>
+
+            <para>
+                For maximum performance it is recommended to use a simple
+                bootstrap file for the server component. Using
+                <classname>Zend_XmlRpc_Server</classname> inside a
+                <link linkend="zend.controller"><classname>Zend_Controller</classname></link>
+                is strongly discouraged to avoid the overhead.
+            </para>
+
+            <para>
+                Services change over time and while webservices are generally
+                less change intense as code-native <acronym>APIs</acronym>, it
+                is recommended to version your service. Do so to lay grounds to
+                provide compatibility for clients using older versions of your
+                service and manage your service lifecycle including deprecation
+                timeframes.To do so just include a version number into your
+                <acronym>URI</acronym>. It is also recommended to include the
+                remote protocol name in the <acronym>URI</acronym> to allow easy
+                integration of upcoming remoting technologies.
+                http://myservice.ws/<emphasis>1.0/XMLRPC/</emphasis>.
+            </para>
+        </sect3>
+
+        <sect3 id="zend.xmlrpc.server.anatomy.expose">
+            <title>What to expose?</title>
+
+            <para>
+                Most of the time it is not sensible to expose business objects
+                directly. Business objects are usually small and under heavy
+                change, because change is cheap in this layer of your
+                application. Once deployed and adopted, web services are hard to
+                change. Another concern is <acronym>I/O</acronym> and latency:
+                the best webservice calls are those not happening. Therefore
+                service calls need to be more coarse-grained than usual business
+                logic is. Often an additional layer in front of your business
+                objects makes sense. This layer is sometimes referred to as <ulink
+                    url="http://martinfowler.com/eaaCatalog/remoteFacade.html">Remote
+                    Facade</ulink>.
+                Such a service layer adds a coarse grained interface on top of
+                your business logic and groups verbose operations into smaller
+                ones.
+            </para>
+        </sect3>
+    </sect2>
+
     <sect2 id="zend.xmlrpc.server.conventions">
         <title>規約</title>
         <para>
@@ -144,11 +195,12 @@ function myFunc($val1, $val2, $val3)
 }
 ]]></programlisting>
 
-        <para>
-            しかし、注意すべきことがあります。複数のシグネチャを定義すると、
-            それを利用する開発者を混乱させてしまいます。
-            一般論として、<acronym>XML-RPC</acronym> のメソッドは複数のシグネチャを持たないほうがいいでしょう。
-        </para>
+        <note>
+            <para>
+                複数のシグネチャを定義すると、それを利用する開発者を混乱させてしまいます。
+                物事を簡単にするために、 <acronym>XML-RPC</acronym> サービスのメソッドは単純なシグネチャだけを持つべきでしょう。
+            </para>
+        </note>
     </sect2>
 
     <sect2 id="zend.xmlrpc.server.namespaces">
@@ -254,7 +306,7 @@ Zend_XmlRpc_Server_Fault::attachFaultException('My_Project_Exception');
             他のプロジェクトの例外を継承した例外クラスを利用するのなら、
             一連のクラス群を一度にホワイトリストに登録することもできます。
             <classname>Zend_XmlRpc_Server_Exceptions</classname> は常にホワイトリストに登録されており、
-            固有の内部エラー (メソッドが未定義であるなど) を報告することができます。
+            固有の内部エラー (メソッドが未定義であるなど) を報告できます。
         </para>
 
         <para>
@@ -274,7 +326,7 @@ Zend_XmlRpc_Server_Fault::attachFaultException('My_Project_Exception');
         </para>
         <para>
             使用するリソースの量を軽減するために、<classname>Zend_XmlRpc_Server_Cache</classname>
-            を用いてリクエスト間でサーバ定義をキャッシュすることができます。
+            を用いてリクエスト間でサーバ定義をキャッシュできます。
             <methodname>__autoload()</methodname> と組み合わせることで、これはパフォーマンスを劇的に向上させます。
         </para>
         <para>
@@ -318,7 +370,8 @@ echo $server->handle();
             以下のいくつかの使用例で、開発者が使用できるオプションを説明します。
             各使用例は、それまでに紹介した例に追加していく形式になります。
         </para>
-        <sect3 id="zend.xmlrpc.server.use.case1">
+
+        <example id="zend.xmlrpc.server.use.attach-function">
             <title>基本的な使用法</title>
 
             <para>
@@ -328,10 +381,10 @@ echo $server->handle();
 
             <programlisting language="php"><![CDATA[
 /**
- * 値の MD5 sum を返します
+ * 値の MD5 合計を返します
  *
  * @param string $value md5sum を計算する値
- * @return string 値の MD5 sum
+ * @return string 値の MD5 合計
  */
 function md5Value($value)
 {
@@ -342,9 +395,9 @@ $server = new Zend_XmlRpc_Server();
 $server->addFunction('md5Value');
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case2">
+        <example id="zend.xmlrpc.server.use.attach-class">
             <title>クラスのアタッチ</title>
 
             <para>
@@ -359,9 +412,109 @@ $server = new Zend_XmlRpc_Server();
 $server->setClass('Services_Comb');
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case3">
+        <!-- TODO : to be translated -->
+        <example id="zend.xmlrpc.server.use.attach-class-with-arguments">
+            <title>Attaching a class with arguments</title>
+
+            <para>
+                The following example illustrates how to attach a class' public
+                methods and passing arguments to its methods. This can be used to specify certain
+                defaults when registering service classes.
+            </para>
+
+            <programlisting language="php"><![CDATA[
+class Services_PricingService
+{
+    /**
+     * Calculate current price of product with $productId
+     *
+     * @param ProductRepository $productRepository
+     * @param PurchaseRepository $purchaseRepository
+     * @param integer $productId
+     */
+    public function calculate(ProductRepository $productRepository,
+                              PurchaseRepository $purchaseRepository,
+                              $productId)
+    {
+        ...
+    }
+}
+
+$server = new Zend_XmlRpc_Server();
+$server->setClass('Services_PricingService',
+                  'pricing',
+                  new ProductRepository(),
+                  new PurchaseRepository());
+]]></programlisting>
+
+            <para>
+                The arguments passed at <methodname>setClass()</methodname> at server construction time are
+                injected into the method call <command>pricing.calculate()</command> on remote invokation.
+                In the example above, only the argument <code>$purchaseId</code> is expected from the client.
+            </para>
+        </example>
+
+        <example id="zend.xmlrpc.server.use.attach-class-with-arguments-constructor">
+            <title>Passing arguments only to constructor</title>
+
+            <para>
+                <classname>Zend_XmlRpc_Server</classname> allows to restrict argument passing to
+                constructors only. This can be used for constructor dependency injection.
+                To limit injection to constructors, call <methodname>sendArgumentsToAllMethods</methodname>
+                and pass <code>false</code> as an argument. This disables the default behavior of all arguments
+                being injected into the remote method. In the example below the instance of
+                <classname>ProductRepository</classname> and <classname>PurchaseRepository</classname> is only
+                injected into the constructor of <classname>Services_PricingService2</classname>.
+            </para>
+
+            <programlisting language="php"><![CDATA[
+class Services_PricingService2
+{
+    /**
+     * @param ProductRepository $productRepository
+     * @param PurchaseRepository $purchaseRepository
+     */
+    public function __construct(ProductRepository $productRepository,
+                                PurchaseRepository $purchaseRepository)
+    {
+        ...
+    }
+
+    /**
+     * Calculate current price of product with $productId
+     *
+     * @param integer $productId
+     * @return double
+     */
+    public function calculate($productId)
+    {
+        ...
+    }
+}
+
+$server = new Zend_XmlRpc_Server();
+$server->sendArgumentsToAllMethods(false);
+$server->setClass('Services_PricingService2',
+                  'pricing',
+                  new ProductRepository(),
+                  new PurchaseRepository());
+]]></programlisting>
+        </example>
+
+        <example id="zend.xmlrpc.server.use.attach-instance">
+            <title>Attaching a class instance</title>
+
+            <para>
+                <methodname>setClass()</methodname> allows to register a previously instantiated
+                object at the server. Just pass an instance instead of the class name. Obviously
+                passing arguments to the constructor is not possible with pre-instantiated
+                objects.
+            </para>
+        </example>
+
+        <example id="zend.xmlrpc.server.use.attach-several-classes-namespaces">
             <title>名前空間を用いた複数のクラスのアタッチ</title>
 
             <para>
@@ -379,9 +532,9 @@ $server->setClass('Services_Brush', 'brush'); // メソッドをコールする
 $server->setClass('Services_Pick', 'pick');   // メソッドをコールするには pick.* とします
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case4">
+        <example id="zend.xmlrpc.server.use.exceptions-faults">
             <title>fault レスポンス用に使用する例外の指定</title>
 
             <para>
@@ -404,11 +557,22 @@ $server->setClass('Services_Brush', 'brush'); // メソッドをコールする
 $server->setClass('Services_Pick', 'pick');   // メソッドをコールするには pick.* とします
 echo $server->handle();
 ]]></programlisting>
-        </sect3>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case5">
-            <title>独自のリクエストオブジェクトの利用</title>
+        <example id="zend.xmlrpc.server.use.custom-request-object">
+            <title>独自のリクエスト及びレスポンスオブジェクトの利用</title>
 
+            <!-- TODO : to be translated -->
+            <para>
+                Some use cases require to utilize a custom request object.
+                For example, <acronym>XML/RPC</acronym> is not bound to
+                <acronym>HTTP</acronym> as a transfer protocol. It is possible to use
+                other transfer protocols like <acronym>SSH</acronym> or telnet to send
+                the request and response data over the wire. Another use case is
+                authentication and authorization. In case of a different transfer
+                protocol, one need to change the implementation to read request data.
+            </para>
+            
             <para>
                 次の例は、独自のリクエストオブジェクトを作成し、
                 それをサーバに渡して処理します。
@@ -434,10 +598,10 @@ $request = new Services_Request();
 
 echo $server->handle($request);
 ]]></programlisting>
-        </sect3>
+        </example>
 
-        <sect3 id="zend.xmlrpc.server.use.case6">
-            <title>独自のレスポンスオブジェクトの利用</title>
+        <example id="zend.xmlrpc.server.use.custom-response-object">
+            <title>独自のレスポンスクラスの指定</title>
 
             <para>
                 次の例は、独自のレスポンスクラスを作成し、
@@ -468,9 +632,13 @@ $server->setResponseClass('Services_Response');
 
 echo $server->handle($request);
 ]]></programlisting>
-        </sect3>
+        </example>
+    </sect2>
+
+    <sect2 id="zend.xmlrpc.server.performance">
+        <title>パフォーマンスの最適化</title>
 
-        <sect3 id="zend.xmlrpc.server.use.case7">
+        <example id="zend.xmlrpc.server.performance.caching">
             <title>リクエスト間でのサーバ定義のキャッシュ</title>
 
             <para>
@@ -504,7 +672,68 @@ $server->setResponseClass('Services_Response');
 
 echo $server->handle($request);
 ]]></programlisting>
-        </sect3>
+        </example>
+
+        <!-- TODO : to be translated -->
+        <note>
+            <para>
+                The server cache file should be located outside the document root.
+            </para>
+        </note>
+
+        <example id="zend.xmlrpc.server.performance.xmlgen">
+
+            <title>Optimizing XML generation</title>
+
+            <para>
+                <classname>Zend_XmlRpc_Server</classname> uses
+                <classname>DOMDocument</classname> of <acronym>PHP</acronym>
+                extension <code>ext/dom</code> to generate it's
+                <acronym>XML</acronym> output. While <code>ext/dom</code> is
+                available on a lot of hosts it is not exactly the fastest.
+                Benchmarks have shown, that <classname>XMLWriter</classname>
+                from <code>ext/xmlwriter</code> performs better.
+            </para>
+
+            <para>
+                If <code>ext/xmlwriter</code> is available on your host, you can
+                select a the <classname>XMLWriter</classname>-based generator
+                to leaverage the performance differences.
+            </para>
+
+            <programlisting language="php"><![CDATA[
+require_once 'Zend/XmlRpc/Server.php';
+require_once 'Zend/XmlRpc/Generator/XMLWriter.php';
+
+Zend_XmlRpc_Value::setGenerator(new Zend_XmlRpc_Generator_XMLWriter());
+
+$server = new Zend_XmlRpc_Server();
+...
+]]></programlisting>
+        </example>
+
+        <note>
+            <title>Benchmark your application</title>
+
+            <para>
+                Performance is determined by a lot of parameters and
+                benchmarks only apply for the specific test case. Differences
+                come from PHP version, installed extensions, webserver and
+                operating system just to name a few. Please make sure to
+                benchmark your application on your own and decide which
+                generator to use based on <emphasis>your</emphasis> numbers.
+            </para>
+        </note>
+
+        <note>
+            <title>Benchmark your client</title>
+
+            <para>
+                This optimization makes sense for the client side too. Just
+                select the alternate <acronym>XML</acronym> generator before
+                doing any work with <classname>Zend_XmlRpc_Client</classname>.
+            </para>
+        </note>
     </sect2>
 </sect1>
 <!--