documentation/manual/pl/module_specs/Zend_XmlRpc_Server.xml

   1 <sect1 id="zend.xmlrpc.server">
   2     <title>Zend_XmlRpc_Server</title>
   3
   4     <sect2 id="zend.xmlrpc.server.introduction">
   5         <title>Wprowadzenie</title>
   6
   7         <para>Klasa Zend_XmlRpc_Server jest przeznaczona do użycia jako
   8             pełnofunkcjonalny serwer XML-RPC, zgodny ze
   9             <ulink url="http://www.xmlrpc.com/spec">specyfikacją przedstawioną
  10             na www.xmlrpc.com</ulink>. Dodatkowo implementuje ona metodę
  11             system.multicall(), pozwalającą na wywołanie wielu metod podczas
  12             jednego żądania.
  13         </para>
  14     </sect2>
  15
  16     <sect2 id="zend.xmlrpc.server.usage">
  17         <title>Podstawowe użycie</title>
  18
  19         <para>
  20             Przykład najbardziej podstawowego przypadku użycia:
  21         </para>
  22
  23         <programlisting role="php"><![CDATA[
  24 $server = new Zend_XmlRpc_Server();
  25 $server->setClass('My_Service_Class');
  26 echo $server->handle();
  27 ]]>
  28         </programlisting>
  29     </sect2>
  30
  31     <sect2 id="zend.xmlrpc.server.structure">
  32         <title>Struktura serwera</title>
  33
  34         <para>
  35             Zend_XmlRpc_Server składa się z wielu różnych komponentów, od
  36             samego serwera, przez obiekty żądania, obiekty odpowiedzi aż do
  37             obiektów błędów.
  38         </para>
  39
  40         <para>
  41             Aby uruchomić serwer Zend_XmlRpc_Server, programista musi dołączyć
  42             jedną lub więcej klas albo funkcji do serwera, za pomocą metod
  43             <code>setClass()</code> oraz <code>addFunction()</code>.
  44         </para>
  45
  46         <para>
  47             Kiedy jest to już zrobione, możesz przekazać obiekt
  48             <code>Zend_XmlRpc_Request</code> do metody
  49             <code>Zend_XmlRpc_Server::handle()</code>, lub zostanie utworzona
  50             instancja obiektu <code>Zend_XmlRpc_Request_Http</code> w przypadku
  51             gdy nie zostanie zapewniony żaden obiekt -- spowoduje to pobieranie
  52             żądań z <code>php://input</code>.
  53         </para>
  54
  55         <para>
  56             <code>Zend_XmlRpc_Server::handle()</code> próbuje wtedy uruchomić
  57             odpowiednią klasę obsługującą, zależnie od użytej metody dostępu.
  58             Zwraca wtedy obiekt oparty na <code>Zend_XmlRpc_Response</code> lub
  59             obiekt <code>Zend_XmlRpc_Server_Fault</code>. Oba te obiekty mają
  60             dostępne metody <code>__toString()</code>, ktore tworzą poprawne
  61             odpowiedzi XML-RPC, pozwalając na bezpośrednie ich wyświetlenie.
  62         </para>
  63     </sect2>
  64
  65     <sect2 id="zend.xmlrpc.server.conventions">
  66         <title>Konwencje</title>
  67         <para>
  68             Zend_XmlRpc_Server pozwala programiście dołączać funkcje oraz metody
  69             klas jako uruchamialne metody XML-RPC. Poprzez Zend_Server_Reflection,
  70             przeprowadzana jest introspekcja dla wszystkich dołączanych metod,
  71             używając bloków dokumentacji funkcji i metod do określenia opisów
  72             pomocy dla metod oraz sygnatur metod.
  73         </para>
  74
  75         <para>
  76             XML-RPC nie mają w typach PHP dokładnych odpowiedników. Jednak skrypt
  77             spróbuje dopasować najlepszy typ na podstawie wartości znajdujących
  78             się w polach @param oraz @return. Niektóre typy XML-RPC nie mają
  79             dokładnych odpowiedników w typach PHP, więc powinny być rzutowane
  80             używając typów XML-RPC w komentarzach phpdoc. Są to:
  81         </para>
  82
  83         <itemizedlist>
  84             <listitem><para>dateTime.iso8601, łańcuch znaków sformatowany jako
  85                     YYYYMMDDTHH:mm:ss</para></listitem>
  86             <listitem><para>base64, dane zakodowane jako base64</para></listitem>
  87             <listitem><para>struct, dowolna tablica asocjacyjna</para></listitem>
  88         </itemizedlist>
  89
  90         <para>
  91             Przykład wywołania przykładowej funkcji:
  92         </para>
  93
  94         <programlisting role="php"><![CDATA[
  95 /**
  96 * To jest przykładowa funkcja
  97 *
  98 * @param base64 $val1 Dane zakodowane jako Base64
  99 * @param dateTime.iso8601 $val2 Data ISO
 100 * @param struct $val3 Tablica asocjacyjna
 101 * @return struct
 102 */
 103 function myFunc($val1, $val2, $val3)
 104 {
 105 }
 106 ]]>
 107         </programlisting>
 108
 109         <para>
 110             PhpDocumentor nie przeprowadza weryfikacji typów określonych dla
 111             parametrów lub zwracanych wartości, więc nie będzie to miało wpływu
 112             na twoją dokumentację API
 113             Providing the hinting is necessary, however, when the
 114             server is validating the parameters provided to the method call.
 115         </para>
 116
 117         <para>
 118             Poprawne jest określenie wielu typów zarówno dla parametrów jak i
 119             dla zwracanych wartości; specyfikacja XML-RPC sugeruje nawet, że
 120             metoda system.methodSignature powinna zwracać tablicę wszystkich
 121             możliwych sygnatur metody (np. wszystkie możliwe kombinacje
 122             parametrów i zwracanych wartości). Możesz to zrobić tak jak robisz
 123             to w PhpDocumentor, używając operatora '|':
 124         </para>
 125
 126         <programlisting role="php"><![CDATA[
 127 /**
 128 * To jest przykładowa funkcja
 129 *
 130 * @param string|base64 $val1 Łańcuch znaków lub dane zakodowane jako base64
 131 * @param string|dateTime.iso8601 $val2 Łańcuch znaków lub data ISO
 132 * @param array|struct $val3 Normalnie indeksowana tablica lub tablica asocjacyjna
 133 * @return boolean|struct
 134 */
 135 function myFunc($val1, $val2, $val3)
 136 {
 137 }
 138 ]]>
 139         </programlisting>
 140
 141         <para>
 142             Jedna uwaga: dopuszczanie do utworzenia wielu różnych sygnatur może
 143             doprowadzić do dezorientacji programistów używających serwisów;
 144             W zasadzie metoda XML-RPC powinna mieć tylko jedną sygnaturę.
 145         </para>
 146     </sect2>
 147
 148     <sect2 id="zend.xmlrpc.server.namespaces">
 149         <title>Używanie przestrzeni nazw</title>
 150
 151         <para>
 152             XML-RPC posiada system przestrzeni nazw; najprościej mówiąc, pozwala
 153             to na grupowanie metod XML-RPC w przestrzenie nazw oddzielone
 154             znakiem kropki. Ułatwia to zapobieganie konfliktom pomiędzy metodami
 155             pochodzącymi z rożnych klas. Przykładowo, serwer XML-RPC powinien
 156             udostępniać kilka metod w przestrzeni nazw 'system':
 157         </para>
 158
 159         <itemizedlist>
 160             <listitem><para>system.listMethods</para></listitem>
 161             <listitem><para>system.methodHelp</para></listitem>
 162             <listitem><para>system.methodSignature</para></listitem>
 163         </itemizedlist>
 164
 165         <para>
 166             Wewnątrz odpowiada to metodom o tych samych w obiekcie
 167             Zend_XmlRpc_Server.
 168         </para>
 169
 170         <para>
 171             Jeśli chcesz dodać przestrzenie nazw do metod, które oferujesz, po
 172             prostu podaj przestrzeń nazw do odpowiedniej metody wtedy, gdy
 173             dołączasz funkcję lub klasę:
 174         </para>
 175
 176         <programlisting role="php"><![CDATA[
 177 // Wszystkie publiczne metody klasy My_Service_Class będą dostępne jako
 178 // myservice.METHODNAME
 179 $server->setClass('My_Service_Class', 'myservice');
 180
 181 // Funkcja 'somefunc' będzie dostępna jako funcs.somefunc
 182 $server->addFunction('somefunc', 'funcs');
 183 ]]>
 184         </programlisting>
 185     </sect2>
 186
 187     <sect2 id="zend.xmlrpc.server.request">
 188         <title>Własny obiekt żądania</title>
 189
 190         <para>
 191             W większości przypadków będziesz używał domyślnego obiektu żądania
 192             dostarczanego przez Zend_XmlRpc_Server, którym jest obiekt
 193             Zend_XmlRpc_Request_Http. Jednak czasem możesz chcieć aby usługa
 194             XML-RPC była dostępna przez CLI, GUI lub inne środowisko, lub możesz
 195             chcieć zapisywać informacje o przychodzących żądaniach. Aby to
 196             zrobić, możesz utworzyć własny obiekt żądania, który rozszerza
 197             obiekt Zend_XmlRpc_Request. Najważniejszą rzeczą jest zapamiętanie
 198             aby zawsze implementować metody getMethod() oraz getParams() co
 199             pozwoli na to, że serwer XML-RPC będzie mógł pobrać te informacje w
 200             celu uruchomienia żądania.
 201         </para>
 202     </sect2>
 203
 204     <sect2 id="zend.xmlrpc.server.response">
 205         <title>Własne odpowiedzi</title>
 206
 207         <para>
 208             Podobnie jak obiekty żądania, Zend_XmlRpc_Server może zwracać własne
 209             obiekty odpowiedzi; domyślnie zwracany jest obiekt
 210             Zend_XmlRpc_Response_Http, który wysyła odpowiedni nagłówek HTPP
 211             Content-Type do użycia z XML-RPC. Możliwym powodem użycia własnego
 212             obiektu może być potrzeba logowania odpowiedzi, lub wysyłanie
 213             odpowiedzi spowrotem do STDOUT.
 214         </para>
 215
 216         <para>
 217             Aby użyć własnej klasy odpowiedzi, użyj metody
 218             Zend_XmlRpc_Server::setResponseClass() przed wywołaniem handle().
 219         </para>
 220     </sect2>
 221
 222     <sect2 id="zend.xmlrpc.server.fault">
 223         <title>Obsługa wyjątków poprzez odpowiedzi błędów</title>
 224
 225         <para>
 226             Obiekt Zend_XmlRpc_Server łapie wyjątki wyrzucone przez uruchomioną
 227             metodę i generuje odpowiedź błędu (fault) wtedy gdy taki wyjątek
 228             zostanie złapany. Domyślnie informacje o wyjątkach i ich kody nie są
 229             używane w odpowiedzi błędu. Jest to celowe zachowanie chroniące twój
 230             kod; wiele wyjątków ujawnia dużo informacji o kodzie oraz środowisku,
 231             czemu programista powinien zapobiec (dobrym przykładem mogą być
 232             informacje o wyjątkach związanych z bazą danych)
 233         </para>
 234
 235         <para>
 236             Klasy wyjątków, które mają być użyte jako odpowiedzi błędów mogą być
 237             dodane do listy dozwolonych wyjątków. Aby to zrobić wystarczy użyć
 238             metody Zend_XmlRpc_Server_Fault::attachFaultException() w celu
 239             przekazania klasy wyjątku do listy dozwolonych wyjątków:
 240         </para>
 241
 242         <programlisting role="php"><![CDATA[
 243 Zend_XmlRpc_Server_Fault::attachFaultException('My_Project_Exception');
 244 ]]>
 245         </programlisting>
 246
 247         <para>
 248             Jeśli dodasz do listy wyjątków klasę wyjątku z którego dziedziczą
 249             inne wyjątki, możesz w ten sposób dodać do listy całą rodzinę
 250             wyjątków za jednym razem. Wyjątki Zend_XmlRpc_Server_Exceptions
 251             zawsze znajdują się na liście dozwolonych wyjątków, aby pozwolić na
 252             informowanie o specyficznych wewnętrznych błędach (niezdefiniowanie
 253             metody itp.).
 254         </para>
 255
 256         <para>
 257             Każdy wyjątek spoza listy dozwolonych wyjątków spowoduje
 258             wygenerowanie odpowiedzi błędu o kodzie '404' i informacji
 259             'Unknown error' (Nieznany błąd).
 260         </para>
 261     </sect2>
 262
 263     <sect2 id="zend.xmlrpc.server.caching">
 264         <title>Buforowanie definicji serwera pomiędzy żądaniami</title>
 265         <para>
 266             Dołączanie wielu klas do instancji serwera XML-RPC może zajmować
 267             wiele zasobów; za pomocą Reflection API (przez Zend_Server_Reflection)
 268             musi być dokonana introspekcja każdej klasy co w rezultacie wygeneruje
 269             listę wszystkich możliwych sygnatur metod w celu przekazania jej
 270             do klasy serwera.
 271         </para>
 272         <para>
 273             Aby zredukować straty wydajności, możemy użyć obiektu
 274             Zend_XmlRpc_Server_Cache do buforowania definicji serwera pomiędzy
 275             żądaniami. Gdy połączymy to z funkcją __autoload(), może to mocno
 276             zwiększyć wydajność.
 277         </para>
 278         <para>
 279             Przykładowe użycie:
 280         </para>
 281         <programlisting role="php"><![CDATA[
 282 function __autoload($class)
 283 {
 284     Zend_Loader::loadClass($class);
 285 }
 286
 287 $cacheFile = dirname(__FILE__) . '/xmlrpc.cache';
 288 $server = new Zend_XmlRpc_Server();
 289
 290 if (!Zend_XmlRpc_Server_Cache::get($cacheFile, $server)) {
 291     require_once 'My/Services/Glue.php';
 292     require_once 'My/Services/Paste.php';
 293     require_once 'My/Services/Tape.php';
 294
 295     $server->setClass('My_Services_Glue', 'glue');   // przestrzeń nazw glue
 296     $server->setClass('My_Services_Paste', 'paste'); // przestrzeń nazw paste
 297     $server->setClass('My_Services_Tape', 'tape');   // przestrzeń nazw tape
 298
 299     Zend_XmlRpc_Server_Cache::save($cacheFile, $server);
 300 }
 301
 302 echo $server->handle();
 303 ]]>
 304         </programlisting>
 305         <para>
 306             Powyższy przykład próbuje pobrać definicję serwera z pliku bufora
 307             xmlrpc.cache znajdującego się w tym samym katalogu co skrypt. Jeśli
 308             się to nie uda, załaduje on potrzebne klasy serwisu, dołączy do
 309             instancji serwera i spróbuje utworzyć nowy plik bufora z definicją
 310             sderwera.
 311         </para>
 312     </sect2>
 313
 314     <sect2 id="zend.xmlrpc.server.use">
 315         <title>Przykład użycia</title>
 316         <para>
 317             Poniżej znajduje się kilka przykładów użycia, pokazując pełne
 318             spektrum opcji dostępnych dla programistów. Każdy z przykładów
 319             użycia jest oparty na poprzednich przykładach.
 320         </para>
 321         <sect3 id="zend.xmlrpc.server.use.case1">
 322             <title>Podstawowe użycie</title>
 323
 324             <para>
 325                 Poniższy przykład dołącza funkcję jaką uruchamialną przez
 326                 XML-RPC metodę i obsługuje przychodzące wywołania.
 327             </para>
 328
 329             <programlisting role="php"><![CDATA[
 330 /**
 331  * Zwraca sumę MD5 zadanej wartości
 332  *
 333  * @param string $value wartość do obliczenia sumy md5
 334  * @return string MD5 suma wartości
 335  */
 336 function md5Value($value)
 337 {
 338     return md5($value);
 339 }
 340
 341 $server = new Zend_XmlRpc_Server();
 342 $server->addFunction('md5Value');
 343 echo $server->handle();
 344 ]]>
 345             </programlisting>
 346         </sect3>
 347
 348         <sect3 id="zend.xmlrpc.server.use.case2">
 349             <title>Dołączanie klasy</title>
 350
 351             <para>
 352                 Poniższy przykład pokazuje dołączanie publicznych metod klasy
 353                 jako uruchamialnych metod XML-RPC.
 354             </para>
 355
 356             <programlisting role="php"><![CDATA[
 357 $server = new Zend_XmlRpc_Server();
 358 $server->setClass('Services_Comb');
 359 echo $server->handle();
 360 ]]>
 361             </programlisting>
 362         </sect3>
 363
 364         <sect3 id="zend.xmlrpc.server.use.case3">
 365             <title>Dołączanie wielu klas używając przestrzeni nazw</title>
 366
 367             <para>
 368                 Poniższy przykład pokazuje dołączanie kilku klas, każdej z
 369                 własną przestrzenią nazw.
 370             </para>
 371
 372             <programlisting role="php"><![CDATA[
 373 $server = new Zend_XmlRpc_Server();
 374 $server->setClass('Services_Comb', 'comb');   // metody wywoływane jako comb.*
 375 $server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
 376 $server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*
 377 echo $server->handle();
 378 ]]>
 379             </programlisting>
 380         </sect3>
 381
 382         <sect3 id="zend.xmlrpc.server.use.case4">
 383             <title>Określenie wyjątków dla odpowiedzi błędów</title>
 384
 385             <para>
 386                 Poniższy przykład pozwala dowolnej klasie pochodzącej od
 387                 Services_Exception na przekazywanie informacji o wyjątkach w
 388                 postaci kodu i wiadomości w odpowiedzi błędu.
 389             </para>
 390
 391             <programlisting role="php"><![CDATA[
 392 // Pozwala na wyrzucanie wyjątku Services_Exceptions dla odpowiedzi błędu
 393 Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');
 394
 395 $server = new Zend_XmlRpc_Server();
 396 $server->setClass('Services_Comb', 'comb');   // metody wywoływane jako comb.*
 397 $server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
 398 $server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*
 399 echo $server->handle();
 400 ]]>
 401             </programlisting>
 402         </sect3>
 403
 404         <sect3 id="zend.xmlrpc.server.use.case5">
 405             <title>Użycie własnego obiektu żądania</title>
 406
 407             <para>
 408                 Poniższy przykład tworzy instancję własnego obiektu żądania i
 409                 przekazuje go do obiektu serwera.
 410             </para>
 411
 412             <programlisting role="php"><![CDATA[
 413 // Pozwala na wyrzucanie wyjątku Services_Exceptions dla odpowiedzi błędu
 414 Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');
 415
 416 $server = new Zend_XmlRpc_Server();
 417 $server->setClass('Services_Comb', 'comb');   // metody wywoływane jako comb.*
 418 $server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
 419 $server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*
 420
 421 // Tworzenie obiektu żądania
 422 $request = new Services_Request();
 423
 424 echo $server->handle($request);
 425 ]]>
 426             </programlisting>
 427         </sect3>
 428
 429         <sect3 id="zend.xmlrpc.server.use.case6">
 430             <title>Użycie własnego obiektu odpowiedzi</title>
 431
 432             <para>
 433                 Poniższy przykład pokazuje określanie własnej klasy odpowiedzi
 434                 dla zwracanej odpowiedzi.
 435             </para>
 436
 437             <programlisting role="php"><![CDATA[
 438 // Pozwala na wyrzucanie wyjątku Services_Exceptions dla odpowiedzi błędu
 439 Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');
 440
 441 $server = new Zend_XmlRpc_Server();
 442 $server->setClass('Services_Comb', 'comb');   // metody wywoływane jako comb.*
 443 $server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
 444 $server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*
 445
 446 // Utwórz obiekt żądania
 447 $request = new Services_Request();
 448
 449 // Użyj własnego obiektu żądania
 450 $server->setResponseClass('Services_Response');
 451
 452 echo $server->handle($request);
 453 ]]>
 454             </programlisting>
 455         </sect3>
 456
 457         <sect3 id="zend.xmlrpc.server.use.case7">
 458             <title>Buforowanie definicji serwera pomiędzy żądaniami</title>
 459
 460             <para>
 461                 Poniższy przykład pokazuje buforowanie definicji serwera pomiędzy
 462                 żądaniami.
 463             </para>
 464
 465             <programlisting role="php"><![CDATA[
 466 // Określ plik cache
 467 $cacheFile = dirname(__FILE__) . '/xmlrpc.cache';
 468
 469 // Pozwala na wyrzucanie wyjątku Services_Exceptions dla odpowiedzi błędu
 470 Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');
 471
 472 $server = new Zend_XmlRpc_Server();
 473
 474 // Spróbuj pobrać definicje serwera z bufora
 475 if (!Zend_XmlRpc_Server_Cache::get($cacheFile, $server)) {
 476     $server->setClass('Services_Comb', 'comb');   // metody wywoływane jako comb.*
 477     $server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
 478     $server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*
 479
 480     // Zapisz cache
 481     Zend_XmlRpc_Server_Cache::save($cacheFile, $server));
 482 }
 483
 484 // Utwórz obiekt żądania
 485 $request = new Services_Request();
 486
 487 // Użyj własnej klasy odpowiedzi
 488 $server->setResponseClass('Services_Response');
 489
 490 echo $server->handle($request);
 491 ]]>
 492             </programlisting>
 493         </sect3>
 494     </sect2>
 495 </sect1>