# $SnapHashLicense:
#
# SnapLogic - Open source data services
#
# Copyright (C) 2008-2009, SnapLogic, Inc. All rights reserved.
#
# See http://www.snaplogic.org for more information about
# the SnapLogic project.
#
# This program is free software, distributed under the terms of
# the GNU General Public License Version 2. See the LEGAL file
# at the top of the source tree.
#
# "SnapLogic" is a trademark of SnapLogic, Inc.
#
#
# $
# $Id: snapi.py 9195 2009-10-12 20:41:19Z dmitri $
import urlparse
import os
from snaplogic.common import snap_http_lib
from snaplogic.snapi_base import keys,exec_interface
from snaplogic.snapi_base.resdef import ResDef,PipelineResDef,read_resdef,get_resdef_template
from snaplogic.snapi_base.auth_obj import AuthUser,AuthGroup,AuthAcl
from snaplogic.snapi_base.exceptions import SnapiException
import snapi_base
PIPELINE = keys.PIPELINE_COMPONENT_NAME
_SERVER_URI = None
# This variable is used for internal testing only as described on the wiki page:
# http://moxie.snaplogic.org/NICoWiki/NICo/Development/ContinuousIntegration2
use_java_cc = None
def _initialize(server_uri):
"""
Initialize the snapi module.
This is a snaplogic internal method that should not be called directly by the general users of snapi.
@param server_uri: The URI of the server, if snapi is being imported inside the server or CC.
@type server_uri: str
"""
global _SERVER_URI
_SERVER_URI = server_uri
def user_auth_check(server_uri, credentials=None):
"""
Check whether the supplied credentials are known to the server.
@param server_uri: The URI of the main server.
@type server_uri: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: The string 'KNOWN' or 'UNKNOWN'.
@rtype: string
"""
return snapi_base.auth_check(server_uri, credentials)
def create_user_entry(server_uri, username, password, credentials=None):
"""
Create a new user object on the server and in memory.
This function merely creates an in-memory representation of the
object on the client side. Nothing is created on the server until
the object is being saved.
The object performs any future interaction with the server with
the same credentials that created this object.
@param server_uri: The URI of the main server.
@type server_uri: string
@param username: The desired name of the user.
@type username: string
@param password: The password for the user.
@type password: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: A new AuthUser object.
@rtype: L{AuthUser}
"""
user = AuthUser(username, password, None, None, None, server_uri, credentials)
return user
def get_user_list(server_uri, credentials=None):
"""
Return the list of known users.
This just returns a list of user names. To get actual user objects, use
get_user_entry().
@param server_uri: The URI of the main server.
@type server_uri: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: List of user names (in case of failure an exception will be raised).
@rtype: list of strings
"""
return snapi_base.auth_user_list(server_uri, credentials)
def get_user_entry(server_uri, username, credentials=None):
"""
Return the information for a specified user entry.
@param server_uri: The URI of the main server.
@type server_uri: string
@param username: Name of the user entry.
@type username: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: An initialized user object. Note that the credentials of that
object will be whatever credentials were specified for THIS
request, NOT necessarily the credentials of the user itself.
@rtype: L{AuthUser}
"""
d = snapi_base.auth_user_entry_get(server_uri, username, credentials)
user = AuthUser(d['name'], None, d['description'], d['email'], d['genid'], d['uri'], credentials)
return user
def delete_user_entry(server_uri, username, credentials=None):
"""
Delete the information for a specified user entry.
@param server_uri: The URI of the main server.
@type server_uri: string
@param username: Name of the user entry.
@type username: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: Success message (in case of failure an exception will be raised).
@rtype: string
"""
return snapi_base.auth_user_entry_delete(server_uri, username, credentials)
def get_group_list(server_uri, credentials=None):
"""
Return the list of known users.
This just returns a list of group names. To get actual group objects, use
get_group_entry().
@param server_uri: The URI of the main server.
@type server_uri: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: List of groups (in case of failure an exception will be raised).
@rtype: list
"""
return snapi_base.auth_group_list(server_uri, credentials)
def create_group_entry(server_uri, groupname, credentials=None):
"""
Create a new group object on the server and in memory.
This function merely creates an in-memory representation of the
object on the client side. Nothing is created on the server until
the object is being saved.
The object performs any future interaction with the server with
the same credentials that created this object.
@param server_uri: The URI of the main server.
@type server_uri: string
@param groupname: The desired name of the group.
@type groupname: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: A new AuthGroup object.
@rtype: L{AuthGroup}
"""
group = AuthGroup(groupname, None, None, server_uri, credentials)
return group
def get_group_entry(server_uri, groupname, credentials=None):
"""
Return the information for a specified group entry.
@param server_uri: The URI of the main server.
@type server_uri: string
@param username: Name of the group entry.
@type username: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: An initialized group object.
@rtype: L{AuthGroup}
"""
d = snapi_base.auth_group_entry_get(server_uri, groupname, credentials)
group = AuthGroup(d['name'], d['description'], d['genid'], d['uri'], credentials)
group.set_users(d['users'])
return group
def delete_group_entry(server_uri, groupname, credentials=None):
"""
Delete the information for a specified group entry.
@param server_uri: The URI of the main server.
@type server_uri: string
@param groupname: Name of the group entry.
@type groupname: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: Success message (in case of failure an exception will be raised).
@rtype: string
"""
return snapi_base.auth_group_entry_delete(server_uri, groupname, credentials)
def get_acl_list(server_uri, credentials=None):
"""
Return the list of known ACLs.
@param server_uri: The URI of the main server.
@type server_uri: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: Dictionary of ACLs (in case of failure an exception will be raised).
The key to the dictionary is the ACL name, each entry is a further
dictionary, containing the entries "uri" and "description".
@rtype: dict
"""
return snapi_base.auth_acl_list(server_uri, credentials)
def create_acl_entry(server_uri, aclname, credentials=None):
"""
Create a new ACL object on the server and in memory.
Please note that contrary to resdefs this function actually will
create an entry on the server already. However, only the aclname
is set. If any other attributes of the ACL should be set, for
example description or actual rules, then this needs to be
done via the appropriate setter functions, followed by a call to
the save() method of the object.
@param server_uri: The URI of the main server.
@type server_uri: string
@param aclname: The desired name of the ACL.
@type aclname: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: A new AuthAcl object.
@rtype: L{AuthAcl}
"""
acl = AuthAcl(aclname, None, None, server_uri, credentials)
return acl
def get_acl_entry(server_uri, aclname, credentials=None):
"""
Return the information for a specified ACL entry.
@param server_uri: The URI of the main server.
@type server_uri: string
@param aclname: Name of the ACL entry.
@type aclname: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: An initialized group object.
@rtype: L{AuthAcl}
"""
d = snapi_base.auth_acl_entry_get(server_uri, aclname, credentials)
acl = AuthAcl(d['name'], d['description'], d['genid'], d['uri'], credentials)
acl.set_rules(d['rules'])
return acl
def delete_acl_entry(server_uri, aclname, credentials=None):
"""
Delete the information for a specified ACL entry.
@param server_uri: The URI of the main server.
@type server_uri: string
@param aclname: Name of the ACL entry.
@type aclname: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: Success message (in case of failure an exception will be raised).
@rtype: string
"""
return snapi_base.auth_acl_entry_delete(server_uri, aclname, credentials)
def create_resource_object(server_uri, name, credentials=None):
"""
Create a new resource definition object.
@param server_uri: The URI of the main server.
@type server_uri: string
@param name: Name of the desired component. If a pipeline
resource is to be created, snapi.PIPELINE should
be specified.
@type name: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: Resource definition object.
@rtype: L{ResDef}
"""
global use_java_cc
if name != PIPELINE:
# If global variable use_java_cc isn't initialized yet,
# read the environment variable and set it below.
if use_java_cc is None:
# Initialize the use_java_cc variable
# Use_java_cc is controlled by setting the environment variable USE_CC to java
# USE_CC=java
use_java_cc = False
if 'USE_CC' in os.environ:
cc = os.environ['USE_CC']
if cc == "java":
use_java_cc = True
# If we're using the Java CC prepend "org." to component name
if use_java_cc:
if not name.startswith("org."):
name = "org." + name
resdef = get_resdef_template(server_uri, name, credentials)
return resdef
def get_resource_object(uri, credentials=None):
"""
Retrieve a resource definition from a specified URI.
@param uri: URI of the resource whose resource definition should be retrieved. The URI
has to be absolute in most cases. However, If this function is being called
inside a component, then the URI can be relative and will resolve to the
server that the component belongs to.
@type uri: string
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return: Resource definition object.
@rtype: L{ResDef}
"""
# Check
inp_uri = urlparse.urlparse(uri)
if not inp_uri.scheme:
if _SERVER_URI is not None:
# This is a relative URI. Let us compute the full URI, in order to retrieve the resef.
server_uri = urlparse.urlparse(_SERVER_URI)
uri = urlparse.urlunparse((server_uri[0], server_uri[1], inp_uri[2], inp_uri[3], inp_uri[4], inp_uri[5]))
else:
raise SnapiException("Need an absolute resource URI when this method is called by an external client")
return read_resdef(uri, credentials)
def upgrade_resources(server_uri, resource_list, credentials=None):
"""
Upgrade specified resources
@param server_uri: URI of the Data Server.
@type server_uri: str
@param resource_list: URIs of the resources to be upgrade
@type resource_list: list
@param credentials: Credentials for the request, consisting of a username/password
tuple.
@type credentials: tuple
@return:
a dictionary with the upgrade results where:
- key is the resource URI
- value is a tuple consisting of three objects:
(needed_upgrade, upgrade_succeeded, error_message)
@rtype: dict
"""
return snapi_base.upgrade_resources(server_uri, resource_list, credentials)
def list_components(server_uri, credentials=None):
"""
List components available at the given server.
@param server_uri: URI of the Data Server.
@type server_uri: str
@return:
a list of available components, as a list of dictionaries, each containing values of the
following keys for every component:
name - user-visible component name
uri - component URI
description - short overview of the component's functionality
capabilities - same as capabilities as a read-only field of a ResDef.
More keys can be added if desired. Here is a sample return value from this function:
@rtype: list
"""
return snapi_base.list_components(server_uri, credentials)
def list_resources(server_uri, credentials=None):
"""
List resources available at the given server.
@param server_uri: URI of the Data Server.
@type server_uri: str
@return: a dict keyed by a URI, whose values are a dictionary containing gen_id, guid and description of
the resource
@rtype: dict
"""
return snapi_base.list_resources(server_uri, None, credentials)
def delete_resource(uri, credentials=None):
"""
Delete the specified resource from the server.
@param uri: The absolute URI of the resource to be deleted.
@type uri: str
@param cred: A 2-tuple containing (username, password)
@type cred: tuple
"""
snapi_base.delete_resource(None, None, uri, True, credentials)
def exec_resource(uri, inputs=None, outputs=None, params=None, credentials=None, name=None):
"""
Execute resource.
@param uri: The absolute URI of the resource to be executed.
@type uri: str
@param inputs: Dictionary with names of the input views as keys. The value can be requested content type or
can be None, if default content_type is fine.
@type inputs: dict
@param outputs: Dictionary with names of the output views as keys. The value can be requested content type or
can be None, if default content_type is fine.
@type outputs: dict
@param params: Dictionary with param name as key and param value as value.
@type params: dict
@param cred: A 2-tuple containing (username, password)
@type cred: tuple
@param name: User defined name for the resource. Could be any string the caller of this
method would like to use to identify the pipeline being invoked. This name does not have to
be unique.
@type name: str
@return: Runtime status URI of the executing resource.
@rtype: str
"""
if name is None:
name = ""
resdef = read_resdef(uri, credentials)
return exec_interface.exec_resource(name, uri, resdef, inputs, outputs, params, credentials)
|