Changes between Version 14 and Version 15 of SeattleGeniClientLib

Changes between Version 14 and Version 15 of SeattleGeniClientLib

Please note that these Trac pages are no longer being updated. Wiki contents/documentation have moved to GitHub.

Changes between Version 14 and Version 15 of SeattleGeniClientLib

Please note that these Trac pages are no longer being updated. Wiki contents/documentation have moved to GitHub.

Changes between Version 14 and Version 15 of SeattleGeniClientLib

Show
Ignore:
Timestamp:
07/05/12 20:36:50 (7 years ago)
Author:
leonwlaw
Comment:

Quick pass of GENI->Clearinghouse. Left link/file references intact.

Legend:

Unmodified
Added
Removed
Modified
  • SeattleGeniClientLib

    v14 v15  
    1 = SeattleGENI XML-RPC Client Library = 
     1        = SeattleClearinghouse XML-RPC Client Library = 
    22[[BR]] 
    3 The SeattleGENI XML-RPC Client Library is a Python XMLRPC client for communicating with the SeattleGENI XML-RPC Interface. 
     3The SeattleClearinghouse XML-RPC Client Library is a Python XMLRPC client for communicating with the SeattleClearinghouse XML-RPC Interface. 
    44 
    5 You can download the the client from here: [source:seattle/trunk/seattlegeni/xmlrpc_clients/seattlegeni_xmlrpc.py SeattleGENI Python XMLRPC Client]. Look for the link to "original format" at the bottom of that page to download the file. 
     5You can download the the client from here: [source:seattle/trunk/seattlegeni/xmlrpc_clients/seattleclearinghouse_xmlrpc.py SeattleClearinghouse Python XMLRPC Client]. Look for the link to "original format" at the bottom of that page to download the file. 
    66 
    77[[BR]] 
    88=== Usage === 
    99  1. Download the client code linked to above (it is a Python module). 
    10   1. In your Python script, import seattlegeni_xmlrpc.[[BR]] 
    11   1. Create an instance (or multiple instances, if desired) of the class seattlegeni_xmlrpc.SeattleGENIClient.[[BR]] 
     10  1. In your Python script, import seattleclearinghouse_xmlrpc.[[BR]] 
     11  1. Create an instance (or multiple instances, if desired) of the class seattleclearinghouse_xmlrpc.SeattleClearinghouseClient.[[BR]] 
    1212     The following parameters can be passed to the constructor: 
    1313     * ''username'': Your username. (Required) 
    1414     * ''private_key_string'': Your private key. (Either this or the api_key is required) 
    1515     * ''api_key'': Your api_key. 
    16      * ''xmlrpc_url'': The url where the SeattleGENI XMLRPC server is located. (Defaults is our main SeattleGENI testbed's xmlrpc url.) 
     16     * ''xmlrpc_url'': The url where the SeattleClearinghouse XMLRPC server is located. (Defaults is our main SeattleClearinghouse testbed's xmlrpc url.) 
    1717     * ''allow_ssl_insecure'': True/False, if set to True, allows SSL to operate in an INSECURE manner. '''Do not use allow_ssl_insecure=True in production code.''' (Default is False) 
    18      * ''ca_certs_file'': The location of a file containing your trusted CA certificates. (Default is a file named `cacert.pem` in the same directory that you place `seattlegeni_xmlrpc.py` in.) 
     18     * ''ca_certs_file'': The location of a file containing your trusted CA certificates. (Default is a file named `cacert.pem` in the same directory that you place `seattleclearinghouse_xmlrpc.py` in.) 
    1919  1. Once a client object has been created, simply invoke the object's methods. 
    2020 
    2121[[BR]] 
    2222=== Using Secure SSL === 
    23 In order to perform secure SSL communication with SeattleGENI: 
     23In order to perform secure SSL communication with SeattleClearinghouse: 
    2424  * You must have M2Crypto installed. 
    2525  * You must set the value of CA_CERTIFICATES_FILE to the location of a PEM 
     
    3131XMLRPC servers that use https but you will be vulnerable to a man-in-the-middle 
    3232attack. To enable this insecure mode, include the argument `allow_ssl_insecure=True` 
    33 when creating a SeattleGENIClient instance. 
     33when creating a SeattleClearinghouseClient instance. 
    3434 
    3535[[BR]] 
    36 === SeattleGENIClient Methods === 
     36=== SeattleClearinghouseClient Methods === 
    3737Please note, these methods are not the same as the XML-RPC API calls. 
    3838The clientlib methods are simply convenient wrappers for those calls.  
    39 As such, most methods here have identical return values as the actual XMLRPC calls. Refer to the [wiki:SeattleGeniApi SeattleGENI XMLRPC API spec] for more info about what these functions return. 
     39As such, most methods here have identical return values as the actual XMLRPC calls. Refer to the [wiki:SeattleGeniApi SeattleClearinghouse XMLRPC API spec] for more info about what these functions return. 
    4040 
    41 Available methods on SeattleGENIClient objects: 
    42   The acquire methods all return a list of acquired resources, following the SeattleGENI XMLRPC API spec. 
     41Available methods on SeattleClearinghouseClient objects: 
     42  The acquire methods all return a list of acquired resources, following the SeattleClearinghouse XMLRPC API spec. 
    4343  * ''acquire_lan_resources(num)'':  Acquires ''num'' LAN vessels. 
    4444  * ''acquire_wan_resources(num)'':  Acquires ''num'' WAN vessels. 
     
    5757 
    5858=== Exceptions === 
    59 The following exceptions can be raised by SeattleGENIClient methods:[[BR]] 
    60   * SeattleGENIError -- Base class for all exceptions raised by the SeattleGENIClient. 
     59The following exceptions can be raised by SeattleClearinghouseClient methods:[[BR]] 
     60  * SeattleClearinghouseError -- Base class for all exceptions raised by the SeattleClearinghouseClient. 
    6161  * !CommunicationError -- Indicates that XMLRPC communication failed. 
    6262  * !InternalError -- Indicates an unexpected error occurred, probably either a bug in this 
    63     client or a bug in SeattleGENI. 
     63    client or a bug in SeattleClearinghouse. 
    6464  * !AuthenticationError -- Indicates an authentication failure (invalid username and/or API key). 
    6565  * !InvalidRequestError -- Indicates that the request is invalid. 
    6666  * !NotEnoughCreditsError -- Indicates that the requested operation requires more vessel credits to 
    6767    be available then the account currently has. 
    68   * !UnableToAcquireResourcesError -- Indicates that the requested operation failed because SeattleGENI was unable 
     68  * !UnableToAcquireResourcesError -- Indicates that the requested operation failed because SeattleClearinghouse was unable 
    6969    to acquire the requested resources. 
    7070 
    71 See the comments in the seattlegeni_xmlrpc.py file for details on when each exception is raised. 
     71See the comments in the seattleclearinghouse_xmlrpc.py file for details on when each exception is raised. 
    7272 
    7373[[BR]] 
    7474=== Example === 
    75 Here is an example of how to use the SeattleGENI XML-RPC Client. This could be a python script which you run.[[BR]] 
     75Here is an example of how to use the SeattleClearinghouse XML-RPC Client. This could be a python script which you run.[[BR]] 
    7676{{{ 
    7777#!python 
    7878""" 
    79 Example of using the seattlegeni_xmlrpc module's SeattleGENIClient. 
     79Example of using the seattleclearinghouse_xmlrpc module's SeattleClearinghouseClient. 
    8080 
    8181This script tries to acquire, renew, and release some vessels and prints out 
     
    8585# This module must be in your python path (for example, in the same directory 
    8686# as the current script is in). 
    87 import seattlegeni_xmlrpc 
     87import seattleclearinghouse_xmlrpc 
    8888 
    8989 
     
    9191 
    9292# Only one of either the API key or the private key is needed. If providing 
    93 # your API key, be sure to pass the API key to the SeattleGENIClient 
     93# your API key, be sure to pass the API key to the SeattleClearinghouseClient 
    9494# constructor below. 
    9595#API_KEY = "your_api_key" 
     
    9797 
    9898# Allowing SSL to be insecure means it will be susceptible to MITM attacks. 
    99 # See the instructions in seattlegeni_xmlrpc.py for using SSL securely. 
     99# See the instructions in seattleclearinghouse_xmlrpc.py for using SSL securely. 
    100100ALLOW_SSL_INSECURE = False 
    101101 
    102102 
    103103def do_example_acquire_renew_release(): 
    104   client = seattlegeni_xmlrpc.SeattleGENIClient(username=USERNAME, 
     104  client = seattleclearinghouse_xmlrpc.SeattleClearinghouseClient(username=USERNAME, 
    105105                                                private_key_string=PRIVATE_KEY_STRING, 
    106106                                                allow_ssl_insecure=ALLOW_SSL_INSECURE) 
     
    124124    # This is a list of dictionaries just like the one above. 
    125125    newly_acquired_vessels = client.acquire_wan_resources(2) 
    126   except seattlegeni_xmlrpc.NotEnoughCreditsError, err: 
     126  except seattleclearinghouse_xmlrpc.NotEnoughCreditsError, err: 
    127127    print("Couldn't acquire resources because we don't have enough vessel " + 
    128128          "credits: " + str(err)) 
    129129    return 
    130   except seattlegeni_xmlrpc.UnableToAcquireResourcesError, err: 
    131     print("Couldn't acquire vessels because SeattleGENI doesn't have enough " + 
     130  except seattleclearinghouse_xmlrpc.UnableToAcquireResourcesError, err: 
     131    print("Couldn't acquire vessels because SeattleClearinghouse doesn't have enough " + 
    132132          "of what we asked for: " + str(err)) 
    133133    return 
     
    141141  try: 
    142142    client.renew_resources(acquired_handle_list) 
    143   except seattlegeni_xmlrpc.NotEnoughCreditsError, err: 
     143  except seattleclearinghouse_xmlrpc.NotEnoughCreditsError, err: 
    144144    # This is probably not going to happen immediately after acquiring vessels. 
    145145    print("Couldn't renew vessels because we are over our vessel credit " + 
     
    165165  try: 
    166166    do_example_acquire_renew_release() 
    167   except seattlegeni_xmlrpc.SeattleGENIError: 
     167  except seattleclearinghouse_xmlrpc.SeattleClearinghouseError: 
    168168    # In a real script, you'd want to handle this. Could be an authentication 
    169169    # error, communication error, etc. You can use the fine-grained exceptions 
    170     # rather than the base exception of SeattleGENIError to do different 
     170    # rather than the base exception of SeattleClearinghouseError to do different 
    171171    # things based on what the actual problem was. 
    172172    raise