1: <?php
  2: 
  3: namespace Logging_Service;
  4: 
  5: //----------------------------------------------------------------------
  6: // Copyright (c) 2012 Raytheon BBN Technologies
  7: //
  8: // Permission is hereby granted, free of charge, to any person obtaining
  9: // a copy of this software and/or hardware specification (the "Work") to
 10: // deal in the Work without restriction, including without limitation the
 11: // rights to use, copy, modify, merge, publish, distribute, sublicense,
 12: // and/or sell copies of the Work, and to permit persons to whom the Work
 13: // is furnished to do so, subject to the following conditions:
 14: //
 15: // The above copyright notice and this permission notice shall be
 16: // included in all copies or substantial portions of the Work.
 17: //
 18: // THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 19: // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 20: // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 21: // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 22: // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 23: // WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 24: // OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS
 25: // IN THE WORK.
 26: //----------------------------------------------------------------------
 27: 
 28: 
 29: /**
 30:  * GENI Clearinghouse Logging Service controller interface
 31:  *<br><br>
 32:  * The GENI Clearinginghouse Logging API allows clients
 33:  * to log events with particular tagging (dictionaries of name/value pairs)
 34:  * and query for logged events matching those name/value pairs
 35:  * <br><br>
 36:  * There is one write interface:
 37: <ul>
 38: <li>   log_event($event_time, $user_id, $attributes, $message) </li>
 39: </ul>
 40:  * <br><br>
 41:  * There are these read interface:
 42: <ul>
 43: <li>   [id, event_time, user_id, message]* <= get_log_entries_by_author($user_id, $num_hours=24) </li>
 44: <li>   [id, event_time, user_id, message]* <= get_log_entries_by_attributes($user_id, $attribute_sets, $num_hours=24) </li>
 45: <li>   [attribute_name, attribute_value]* <= get_attributes_for_log_entry($entry_id) </li>
 46: </ul>
 47:  */
 48: class Logging_Service {
 49: 
 50: /**
 51:  * Log an event and store it in the logging service archive for future query
 52:  * @param dict $args_dict Dictionary containing name/value pairs:
 53: <ul>
 54:    <li>"operation" name of this method ("log_event")</li>
 55:    <li>"event_time" : time of logged event</li>
 56:    <li>"user_id" : ID of user logging event</li>
 57:    <li>"attributes" : dictionary of name/value pairs to be associated with event</li>
 58:   "<li> message" : text message of logged event</li>
 59: </ul>
 60:  * @return int ID of logged event or error code
 61:  *   
 62:  */
 63: function log_event($args_dict)
 64: {
 65: }
 66: 
 67: /**
 68:  * Return list of logged events written by given user
 69:  * @param dict $args_dict Dictionary containing name/value pairs:
 70: <ul>
 71:    <li>"operation" name of this method ("get_log_entries_by_author")</li>
 72:    <li>"earliest_time" : earliest event time to be returned </li>
 73:    <li>"user_id" : ID of user logging event</li>
 74: </ul>
 75:  * @return array List of log events (ID, event_time, user_id, message) written by given user
 76:  *   
 77:  */
 78: function get_log_entries_by_author($args_dict)
 79: {
 80: }
 81: 
 82: /**
 83:  * Return list of logged events matching any of a list of attribute sets
 84:  *   (that is, it is an "OR" of "ANDS" of a dictionary of name/value pairs).
 85:  * 
 86:  * @param dict $args_dict Dictionary containing name/value pairs:
 87: <ul>
 88:    <li>"operation" name of this method ("get_log_entries_by_attributes")</li>
 89:    <li>"earliest_time" : earliest event time to be returned </li>
 90:    <li>"attribute_sets" : List of dictionaries (name/value pairs) for which<
 91: *      if any one is completely matched, the entry is returned. </li>
 92: </ul>
 93:  * @return array List of log events (ID, event_time, user_id, message) matching given list of attribute dictionaries
 94:  *   
 95:  */
 96: function get_log_entries_by_attributes($args_dict)
 97: {
 98: }
 99: 
100: /**
101:  * Return the set of name/value pair attributes associated with given log entry
102:  * @param dict $args_dict Dictionary containing name/value pairs:
103:  <ul>
104:  <li>"operation" name of this method ("get_attributes_for-log_entry")</li>
105:  <li>"entry_id" : ID of log entry for which to lookup attributes</li>
106:  </ul>
107:  * @return dictionary Dictionary of name/value pairs associated with given log entry
108:  */
109: function get_attributes_for_log_entry($args_dict)
110: {
111: }
112: 
113: /**
114:  * Get the version of the API of this particular service provider
115:  * @param dict $args_dict Dictionary containing 'operation'argument
116:  * @return number Version of API of this particular service provider
117:  */
118: function get_version($args_dict)
119: {
120: }
121: 
122: }
123: 
124: ?>
125: