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 /** * 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 ); |