Zend_XmlRpc_ServerВведение
Zend_XmlRpc_Server задуман как полнофункциональный XML-RPC сервер,
следующий » спецификациям,
приведенным на www.xmlrpc.com. Кроме того, он реализует метод
Основы использованияПростой пример использования:
Структура сервераZend_XmlRpc_Server состоит из множества компонент от собственно сервера до объектов запросов, ответов и сообщений об ошибке.
Для загрузки Zend_XmlRpc_Server разработчик должен прикрепить классы
или функции к серверу через методы
После этого можно передать объект Zend_XmlRpc_Request
методу
Затем СоглашенияZend_XmlRpc_Server позволяет прикреплять функции и методы класса - т.н. доступные для диспетчеризации XML-RPC методы. С помощью Zend_Server_Reflection он проводит интроспекцию по всем прикрепленным методам, используя docblock'и функций и методов для установки текста справки и сигнатур методов. Не обязательно, чтобы типы в XML-RPC в точности соответствовали типам в PHP. Тем не менее, для наилучшего результата код пытается угадать наиболее подходящий тип, основываясь на значениях дескрипторов @param и @return. Некоторые типы в XML-RPC не имеют эквивалентов в PHP и должны указываться в PHPDoc. В их список входят:
Пример того, как указывается XML-RPC тип
PhpDocumentor не проводит валидацию типов, определенных для параметров или возвращаемых значений, поэтому это не должно влиять на вашу документацию по API. Указание типов необходимо, если сервер проводит валидацию передаваемых методу параметров. Будет совершенно корректным с точки зрения синтаксиса определять набор возможных типов как для параметров, так и для возвращаемых значений; спецификация XML-RPC даже рекомендует, чтобы system.methodSignature возвращал массив всех возможных сигнатур метода (т.е. все возможные комбинации параметров и возвращаемых значений). Вы можете делать это в точности так же, как это обычно делается для PhpDocumentor - с использованием оператора '|':
Тем не менее, следует учесть, что обилие сигнатур может сбивать с толку разработчиков, использующих данный веб-сервис. Другими словами, следует стремится к тому, чтобы XML-RPC метод имел только одну сигнатуру. Использование пространств именВ XML-RPC есть такое понятие, как пространства имен. Они позволяют группировать методы посредством разделенных точкой имен пространств. Это позволяет предотвратить конфликты имен методов, предоставляемых разными классами. Например, обычно XML-RPC сервер предоставляет несколько методов в пространстве имен 'system':
В нашем случае они соответствуют методам с теми же именами в Zend_XmlRpc_Server. Если необходимо добавить пространства имен для обслуживаемых методов, то просто укажите пространство имен в качестве параметра при вызове соответствующего метода для прикрепления функции или класса:
Использование своих объектов запросов
В большинстве случаев вы можете использовать включенный по умолчанию
в Zend_XmlRpc_Server тип запроса –
Zend_XmlRpc_Request_Http. Тем не
менее, может потребоваться использование XML-RPC в окружениях
CLI, GUI и т.п., журналирование приходящих запросов. Для этого вы
можете создавать свои классы запросов, которые наследуют от
Zend_XmlRpc_Request. Важно помнить при этом, что
методы Использование своих объектов ответов
Как и в случае объектов запросов, Zend_XmlRpc_Server может
возвращать объекты других типов; по умолчанию возвращается
объект Zend_XmlRpc_Response_Http, который отправляет соответствующий
XML-RPC заголовок
Для того чтобы использовать свой класс ответа, вызывайте
метод Обработка исключений через сообщения об ошибкеZend_XmlRpc_Server отлавливает исключения, сгенерированные вызываемым методом и генерирует ответ с сообщением об ошибке сразу, как только исключение поймано. Однако по умолчанию сообщение и код исключения не используются в ответе с сообщением об ошибке. Это сделано намеренно для того, чтобы защитить ваш код, т.к. многие исключения могут выдавать информацию о коде приложения или среде выполнения, обычно предназначенные разработчику.
Тем не менее, можно включать классы исключений в список разрешенных
к отображению в ответах с сообщением об ошибке. Для этого
используйте
Если вы используете класс исключения, от которого наследуют другие исключения в проекте, то можете cразу включить все "семейство" исключений в список разрешенных. Исключения Zend_XmlRpc_Server_Exception всегда находится в списке разрешенных исключений для того, чтобы сообщать об отдельных внутренних ошибках (вызов несуществующего метода и т.д.). На любое исключение, не включенное в список разрешенных, будет генерироваться ответ с кодом ошибки '404' и сообщением 'Unknown error'. Кэширование определений сервера между запросамиПрикрепление большого количества классов к экземпляру XML-RPC сервера может отнимать много ресурсов – каждый класс должен проверяться с использованием Reflection API (через Zend_Server_Reflection), который создает список всех возможных сигнатур методов для передачи классу сервера.
Чтобы снизить ущерб производительности, можно использовать
Zend_XmlRpc_Server_Cache для кэширования определений сервера между
запросами. Если комбинировать его с Пример использования:
В этом примере производится попытка получить определение сервера из файла xmlrpc.cache, находящегося в той же директории, что и скрипт. Если попытка не удалась, то загружаются нужные классы и прикрепляются к экземпляру сервера, затем создается новый файл кэша с определением сервера. Примеры использованияЗдесь приведены несколько примеров использования, демонстрирующих полный набор возможностей, доступных разработчикам. Примеры построены на основе предоставленных ранее примеров. Основы использованияВ примере ниже прикрепляется функция в качестве доступного для диспетчеризации XML-RPC метода и обрабатываются входящие вызовы. Прикрепление классаПример ниже иллюстрирует прикрепление открытых методов класса в качестве доступных для диспетчеризации XML-RPC методов.
Прикрепление нескольких классов с использованием пространств именПример ниже демонстрирует прикрепление нескольких классов, каждый со своим пространством имен.
Указание исключений в качестве используемых для ответов с сообщением об ошибке
Пример ниже позволяет любым наследующим от
Использование своих объектов запросаВ примере ниже инстанцируется специальный объект запроса и передается серверу для обработки.
Использование своих объектов ответаПример ниже демонстрирует указание специального класса ответа для возвращаемого ответа.
Кэширование определений сервера между запросамиПример ниже демонстрирует кэширование определений сервера между запросами.
|