NAME

BuildForge::Services::Connection


SYNOPSIS

        use BuildForge::Services;
        # Connecting and authentication
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($connection, $pass);
        $conn = $conn->authToken($token);
        # Connection functions
        $ping = $conn->ping("ping!");
        $translation = $conn->translate($message);
        
        # Getter and setter functions
        $locale = $conn->getLocale();
        $timezone = $conn->getTimeZone();
        
        $conn->setLocale('en_US');
        $conn->setTimeZone('PDT');
        # Disconnection
        $conn->logout;
        $conn->close;


DESCRIPTION

Connection allows creation and manipulation of a connection to a BuildForge Service Layer server. Through this connection, you can then access and manipulate database objects.


METHODS

new BuildForge::Services::Connection(hostname, portnumber)

Opens a connection to the services layer server and returns a BuildForge::Services::Connection object through which to access that connection.

hostname

The hostname on which the server resides. Defaults to 'localhost'.

portnumber

The port number of the services layer. Defaults to 3966, the standard services layer port.

$connection->authUser(user, password, domain)

Authenticates the connection with the given user login. No BuildForge::Services::DBO objects will allow any activity without the connection having been authenticated against. Returns a token which may be used to log in with in the future for single sign on purposes. This token becomes invalid after this session is over - when the connection has been logged out of with $connection->logout() or closed with $connection->close(). No BuildForge::Services::DBO objects will allow any activity without the connection having been authenticated against.

user

The user login with which to authenticate.

password

The password with which to authenticate.

domain

If the user is an LDAP user, the domain ID (from $ldap->getDomain()) with which to authenticate as previously set up in the BuildForge database - see BuildForge::Services::DBO::LDAP for details. If the user isn't an LDAP user, leave this unset.

$connection->authToken(token)

Authenticates against the given login token if the login token is from a currently active session. Returns the connection object. No BuildForge::Services::DBO objects will allow any activity without the connection having been authenticated against.

token

A login token as returned by $connection->authUser().

$connection->ping(pingString)

Pings the services layer server and returns the ping response object which contains, among other things, the sent ping string.

pingString

The ping string to send.

$connection->translate(msg, locale, tzone)

Contacts the services layer server and has it translate the translation key of the given message, then returns the translated message. then returns the translated string.

msg

The BuildForge::Services::DBO::Message object to be translated.

locale

The locale with which to translate the string. If this is unset, uses the connection's locale which defaults to 'en_US'.

tzone

The time zone used to translate time-related strings. If this is unset, uses the connection's timezone.

$connection->getLocale()

Returns the connection's current locale ID.

$connection->getTimeZone()

Returns the connection's current timezone ID.

$connection->setLocale(locale)

Sets the connection's locale for translation purposes.

locale

The locale ID to use.

$connection->setTimeZone(tzone)

Sets the connection's timezone for date/time translation purposes.

tzone

The timezone ID to use.

$connection->logout()

Logs the user out of the connection. The connection requires reauthentication before BuildForge::Services::DBO objects will allow any actions.

$connection->close()

Closes the connection.


COPYRIGHT

Copyright (c)2006-2007 International Business Machines, Inc. All rights reserved.