The license applies to all software incorporated in the "Vovida
Open Communication Application Library" except for those portions
incorporating third party software specifically identified as being
licensed under separate license.

The Vovida Software License, Version 1.0 
Copyright (c) 2000 Vovida Networks, Inc.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:


1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.


2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

3. The names "VOCAL", "Vovida Open Communication Application Library",
   and "Vovida Open Communication Application Library (VOCAL)" must
   not be used to endorse or promote products derived from this
   software without prior written permission. For written
   permission, please contact vocal@vovida.org.

4. Products derived from this software may not be called "VOCAL", nor
   may "VOCAL" appear in their name, without prior written
   permission of Vovida Networks, Inc.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
NON-INFRINGEMENT ARE DISCLAIMED.  IN NO EVENT SHALL VOVIDA
NETWORKS, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT DAMAGES
IN EXCESS OF $1,000, NOR FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

====================================================================

This software consists of voluntary contributions made by Vovida
Networks, Inc. and many individuals on behalf of Vovida Networks,
Inc.  For more information on Vovida Networks, Inc., please see
<http://www.vovida.org/>.


All third party licenses and copyright notices and other required
legends also need to be complied with as well.

>>> --- Last Updated May 18, 2001 (Wendy Breu) --- <<<

README:

     This README is obsolete.  It is included for historical purposes only.

PURPOSE of psLib (Mascarpone project):

The library is intended for all client applications that need to
access data from the ProvisionServer (PServer).  It provides a
set of API methods (in abstract class ProvisioningInterface)
to clients to do the following operations:

CLASS DESCRIPTION: (high level descriptions of each class's responsibilities)

PSListener: Listener object is contained in the ProvisionInterface object
    listening in a separate thread for any update notification from the 
    Provision Server.

HostInterface: Interface to connect to a server. This instantiates a Reader
and Writer to talk to that particular host.

PSInterface: Manages which host interface is active to handle redundancy. 
    Switches to the other when one fails, and will delay and try both 
    again if both fail.  (This is a legacy class from Vocal 1.0)

PSConnection: object of this class is responsible for synchronous
    TCP communication.  It sends the client's database request to
    and receives the response from the PServer.

PSHttpXMLInterface: this is a concrete class deriving from
    ProvisioningInterface.

PSIFCreator: factory class used to instantiate, getPSIFInstance(),
             a concrete ProvisioningInterface object given the
             active/standby hosts/ports and the interface type
             (see PSCommon::PSIFType).

ProvisioningInterface: abstract class providing a single interface to
    the clients trying to GET/PUT/POST/DELETE information from/to 
    the ProvisionServer.  It is a singleton class, which instantiates 
    the PSListener, and calls PSInterface which instantiates HostInterface 
    which instantiates the PSConnection objects.


HIGH LEVEL FLOW


SAMPLE USAGES:
1) To instantiate a ProvisioningInterface:

    #include "PSIFCreator.hxx"
    #include "ProvisioningInterface.hxx"

    PSIFCreator myPifCreator;
    ProvisioningInterface& pif;
    try
    {
        // myPifCreator returns a PSHttpXMLInterface object:
        pif = myPifCreator.getPSIFInstance(
           "host1", 6005, "host2", 6005, PSCommon::HTTPXML);

        ............. ecordsInDomain("Accounts","uid=100*",myFieldList);
    }
    catch (VException& e)
    {
        // log error 
    }

2) To send a GetRecordsInDomain request to PServer:

    #include "PSDBResult.hxx"

    string domain = "Accounts";
    string filter = "uid=100*";

    // build the field list:
    list<string> myFieldList;
    myFieldList.push_back("uid");
    myFieldList.push_back("phone");
    myFieldList.push_back("foo");

    try {
       Sptr<PSDBResult> res;    // data base result set

       // call getRecordsInDomain() to build a GetRecordsInDomain
       // request.  ProvisioningInterface is responsible for 
       // building a Http message (via PSProtocolService), and
       // send it to PServer.  The response received is 
       // _automatically_ parsed and the keyword value pair
       // placed in a PSDBResult object:
       res = pif.getRecordsInDomain(domain, filter, myFieldList);

       ........

    }
    catch (VException& e)
    {
        .........
    }


PServer DB NOTIFICATION

Client also register for a notification for a given item supplying
the callback function of:

type void call_Back_func(const string& Data, const string& Item, 
                         bool DelFlag)

where:

  Data - is the contents of the item 
  Item - Name of the item
  DelFlag -- Is this item being deleted

Client can register for as many callback functions for a given item in a 
group as they want.

Whenever the item contents are changed on the ProvisionServer, the
call_Back_function is called with the contents of the data item.

One can also register for a group, in which case when a new item is added,
an item is modified, or deleted, they will be called back.

Client also has an option to unregister for update notification for a
given data item or group, and given callback function.  
Please see the attached header file.

Here is an example:

#include "ProvisionInterface.hxx"
#include "VException.hxx"

void notifyUpdate(const string& data, const string& Name, bool delFlag)
{
    cerr << "Received an update notification for item:" << Name << endl;
    cerr << "Received an update notification for Data:" << data << endl;
    cerr << "Is deletion?                            :" << delFlag << endl;
}

int
main(int argc, char** argv)
{
    try 
    {	
        ProvisionInterface& pif = ProvisionInterface::instance();
        pif.registerForUpdate(notifyUpdate, "anItemNameToRead", "group");
        string dRead = pif.readItem("group", "anItemNameToRead");
        event_loop;
    } 
    catch (VException& e)
    {
        cerr << "Network exception ." << e.getDescription() << endl;
    }
    exit(0);
}


// End of File

======================================================================

Copyright 2000-2003, Cisco Systems, Inc.
THE INFORMATION HEREIN IS PROVIDED ON AN "AS IS" BASIS, WITHOUT ANY
WARRANTIES OR REPRESENTATIONS, EXPRESS, IMPLIED OR STATUTORY, INCLUDING
WITHOUT LIMITATION, WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

$Id: README,v 1.2.2.2 2003/03/28 05:25:52 bko Exp $
