Przykładowa biblioteka (PHP)

/**
 * eUczelnia API PHP Client Demonstration
 *
 * Classes in this file demonstrate possible methods of exchanging data with the eUczelnia
 * data warehousing servers through the XML-RPC based eUczelnia API.
 *
 * Data retrieved from the API over XML-RPC connections is cached when possible using memcached.
 *
 * Calls to the API can be performed as follows:
 * <code>
 * <?php
 * // Provide the ID of the current user (0 for anonymous)
 * $user_id = 0;
 *
 * // Define the model object in JSON
 * $json_model = '
 * {
 *     "person": {
 *         "employee.affiliation.faculty": true,
 *         "employee.affiliation.department": true,
 *         "employee.affiliation.unit": true,
 *         "publications": true,
 *         "research": true
 *     }  
 * }';
 *
 * // Define the fields object in JSON
 * $json_fields = '
 * {
 *     "fileds": {
 *         "global_operator": "AND",
 *         "field": [
 *             {
 *                 "field_name": "employee.affiliation.unit.name",
 *                 "operator": "equal",
 *                 "arguments": "Wydział Inżynierii Lądowej i Środowiska"
 *             }
 *         ]
 *     }
 * }';
 *
 * // Make the API call
 * $employee_count = EUczelnia::count($user_id, $json_model, $json_fields);
 * ?>
 * </code>
 *
 * @author Marcin Konrad Ceglarek
 * @copyright 2011, Centrum Usług Informatycznych, Politechnika Gdańska
 */
 
    /**
     * Basic eUczelnia API Client - performs non-cached API calls
     *
     * Provides wrapper functions for all methods of the API (search, count, getElementById, etc)
     */
    class EUczelniaAPIClient
    {
        // eUczelnia API Client key, specific to this application.
        private static $APPLICATION_KEY = '123-abc';
        // eUczelnia API server host URL
        private static $HOST_URL = 'http://miau.oi.pg.gda.pl/class/mailer_server.php';
     
        /**
         * Function contacts the remote API server, and sends an XML-RPC request
         *
         * @param   string    request object encoded as XML
         * @return  string    server response returned as a XML encoded object
         */
        protected static function serverCall($request)
        {
            $context = stream_context_create(array('http' => array(
                'header' => "Content-Type: text/xml\r\nUser-Agent: PHPRPC/1.0 (eKontakt)\r\n",
                'method' => "POST",
                'content' => $request
            )));
 
            /* Getting response */
            $response_xml = file_get_contents(self::$HOST_URL, false, $context);
             
            return $response_xml;
        }
         
        /**
         * Function creates request for count
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   stdClass    fields object
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function count($callerPN, $model, $fields)
        {
 
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("count", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $fields
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
         
        /**
         * Function creates request for search
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   stdClass    fields object
         * @param   stdClass    sort_order object
         * @param   stdClass    return_params object
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function search($callerPN, $model, $fields, $sort_order, $return_params)
        {
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("search", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $fields,
                $sort_order,
                $return_params
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
         
        /**
         * Function creates request for searchAndGet
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   stdClass    fields object
         * @param   stdClass    sort_order object
         * @param   stdClass    return_params object
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function searchAndGet($callerPN, $model, $fields, $sort_order, $return_params)
        {
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("searchAndGet", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $fields,
                $sort_order,
                $return_params
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
         
        /**
         * Function creates request for update
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   array       array of identificators of objects to update
         * @param   stdClass    model object with data to update
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function update($callerPN, $model, $id, $update_model)
        {
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("update", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $id,
                $update_model
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
         
        /**
         * Function creates request for insert
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   stdClass    insert_model object with data to insert
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function insert($callerPN, $model, $insert_model)
        {
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("insert", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $insert_model
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
         
        /**
         * Function creates request for delete
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   array       array of identificators of objects to delete
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function delete($callerPN, $model, $id)
        {
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("delete", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $id
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
         
        /**
         * Function creates request for getElementById
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   array       array of identificators of objects to retrive
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function getElementById($callerPN, $model, $id)
        {
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("getElementById", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $id
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
         
        /**
         * Function creates request for getDistinctElementValues
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   string      name of field, which values will be returned
         * @return  stdClass    server response returned as a standard PHP object
         */
        protected static function getDistinctElementValues($callerPN, $model, $field_name)
        {
            // reading JSON data:
            try {
                $model = json_decode($model);
            } catch (Exception $e){
                throw EUczelniaException ('eUczelnia: Błąd składni JSON obiektu wejściowego: ' . $e->getMessage());
            }
            
            /* Create an XML-RPC request containing the function name and params */
            $request = xmlrpc_encode_request("getDistinctElementValues", array(
                $callerPN,
                self::$APPLICATION_KEY,
                $model,
                $field_name
            ));
             
            return xmlrpc_decode(self::serverCall($request));
        }
    }
     
    /**
     * Cacheing eUczelnia API Client - performs API calls, cached by memcached
     *
     * Provides wrapper functions for all API call related methods of the parent class.
     */
    class EUczelniaCachingClient extends EUczelniaAPIClient
    {
        private static $CACHE_ADDRESS = 'woof.oi.pg.gda.pl';
        private static $CACHE_PORT = 11211;
        private static $DEFAULT_CACHE_TIME = 1800;
         
        /**
         * Retrives content from cache for given cache key value
         *
         * @param   string    cacheKey to retrive
         * @return  string    cached value of the cacheKey
         */
        private static function getCache($cacheKey)
        {
            $memcache = new Memcache;
            if ($memcache->connect(self::$CACHE_ADDRESS, self::$CACHE_PORT))
            {  
                $content = $memcache->get($cacheKey);
                $memcache->close();
            } else {
                $content = false;
            }
            return $content;
        }
         
        /**
         * Sets content in cache table for given cache key
         *
         * @param   string    cacheKey to store data
         * @param   string    string to store
         * @param   int       number of seconds for which data should be stored
         * @return  mixed     on success returns stored value, on failure returns false
         */
        private static function setCache($cacheKey, $content, $time)
        {
            $memcache = new Memcache;
            if ($memcache->connect(self::$CACHE_ADDRESS, self::$CACHE_PORT))
            {
                $content = $memcache->set($cacheKey, $content, 0, $time);
                $memcache->close();
            } else {
                $content = false;
            }
            return $content;
        }
 
        /**
         * Function checks if cache for count is available and stores it if it's not.
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   stdClass    fields object
         * @return  stdClass    server response returned as a standard PHP object
         */
        public static function count($callerPN, $model, $fields)
        {
            // creating cache key for given paramters (cache key should be unique)
            $cacheKey = md5(json_encode($callerPN) . json_encode($model) . json_encode($fields));
             
            // if cache is not available, request data from eUczelnia API
            if (false === ($content = self::getCache($cacheKey)) )
            {  
                $content = parent::count($callerPN, $model, $fields);
                self::setCache($cacheKey, $content, isset($content->cache_time) ? (int)$content->cache_time : self::$DEFAULT_CACHE_TIME );
            }
            return $content;
        }
         
        /**
         * Function checks if cache for search is available and stores it if it's not.
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   stdClass    fields object
         * @param   stdClass    sort_order object
         * @param   stdClass    return_params object
         * @return  stdClass    server response returned as a standard PHP object
         */
        public static function search($callerPN, $model, $fields, $sort_order, $return_params)
        {
            // creating cache key for given paramters (cache key should be unique)
            $cacheKey = md5(json_encode($callerPN) . json_encode($model) . json_encode($fields) . json_encode($sort_order) . json_encode($return_params));
             
            // if cache is not available, request data from eUczelnia API
            if (false === ($content = self::getCache($cacheKey)) )
            {  
                $content = parent::search($callerPN, $model, $fields, $sort_order, $return_params);
                self::setCache($cacheKey, $content, isset($content->cache_time) ? (int)$content->cache_time : self::$DEFAULT_CACHE_TIME);
            }
            return $content;
        }
         
        /**
         * Function checks if cache for searchAndGet is available and stores it if it's not.
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   stdClass    fields object
         * @param   stdClass    sort_order object
         * @param   stdClass    return_params object
         * @return  stdClass    server response returned as a standard PHP object
         */
        public static function searchAndGet($callerPN, $model, $fields, $sort_order, $return_params)
        {
            // creating cache key for given paramters (cache key should be unique)
            $cacheKey = md5(json_encode($callerPN) . json_encode($model) . json_encode($fields) . json_encode($sort_order) . json_encode($return_params) );
             
            // if cache is not available, request data from eUczelnia API
            if (false === ($content = self::getCache($cacheKey)) )
            {  
                $content = parent::searchAndGet($callerPN, $model, $fields, $sort_order, $return_params);
                self::setCache($cacheKey, $content, isset($content->cache_time) ? (int)$content->cache_time : self::$DEFAULT_CACHE_TIME);
            }
            return $content;
        }
         
        /**
         * Function checks if cache for getElementById is available and stores it if it's not.
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   array       array of identificators of objects to retrive
         * @return  stdClass    server response returned as a standard PHP object
         */
        public static function getElementById($callerPN, $model, $id)
        {
            // creating cache key for given paramters (cache key should be unique)
            $cacheKey = md5(json_encode($callerPN) . json_encode($model) . json_encode($id));
             
            // if cache is not available, request data from eUczelnia API
            if (false === ($content = self::getCache($cacheKey)) )
            {  
                $content = parent::getElementById($callerPN, $model, $id);
                self::setCache($cacheKey, $content, isset($content->cache_time) ? (int)$content->cache_time : self::$DEFAULT_CACHE_TIME);
            }
            return $content;
        }
         
        /**
         * Function checks if cache for getDistinctElementValues is available and stores it if it's not.
         *
         * @param   int         caller id
         * @param   stdClass    model object
         * @param   string      name of field, which values will be returned
         * @return  stdClass    server response returned as a standard PHP object
         */
        public static function getDistinctElementValues($callerPN, $model, $field_name)
        {
            // creating cache key for given paramters (cache key should be unique)
            $cacheKey = md5(json_encode($callerPN) . json_encode($model) . json_encode($field_name));
             
            // if cache is not available, request data from eUczelnia API
            if (false === ($content = self::getCache($cacheKey)) )
            {  
                $content = parent::getDistinctElementValues($callerPN, $model, $field_name);
                self::setCache($cacheKey, $content, isset($content->cache_time) ? (int)$content->cache_time : self::$DEFAULT_CACHE_TIME);
            }
            return $content;
        }
    }
     
    /**
     * Wrapper of the cacheing client class - this class should normally be used.
     */
    class EUczelnia extends EUczelniaCachingClient
    {
    }
     
    /**
     * eUczelnia API Related Exception class
     *
     * Provides exceptions related to the API class. Should be extended to log errors, etc.
     *
     * @todo Add error logging/reporting functionality.
     */
    class EUczelniaException extends Exception
    {
    }

Przykład użycia

$user_id = 0;
 
$json_model = '
{
    "person": {
        "employee.affiliation.faculty": true,
        "employee.affiliation.department": true,
        "employee.affiliation.unit": true,
        "publications": true,
        "research": true
    }  
}';
 
$json_fields = '
{
    "fileds": {
        "global_operator": "AND",
        "field": [
            {
                "field_name": "employee.affiliation.unit.name",
                "operator": "equal",
                "arguments": "Wydział Inżynierii Lądowej i Środowiska"
            }
        ]
    }
}';
 
$model = json_decode($json_model);
$fields = json_decode($json_fields);
 
EUczelnia::count($user_id, $model, $fields);