blob: b78d7a7ac73dc8769ee9d9b8873065451e99d840 [file] [log] [blame]
<?php
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
*
* OODT Balance
* Web Application Base Framework
*
* IApplicationDataProvider defines an interface that should be implemented
* by all data providers to simplify the process of integrating and accessing
* multiple heterogeneous data sources. A data source could be a relational
* SQL-like database, a CAS File Manager, an LDAP server, anything that can
* be queried for data.
*
* The interface defines five mandatory functions:
* - __construct: Provide any necessary configuration information but do
* not actually establish a connection to the underlying data
* source.
* - connect: This function does the work of actually connecting to the
* underlying data source. Options can be provided either here
* or in the constructor arguments (or both), but the connection
* to the underlying data source should not be initiated until
* this function is invoked.
* - disconnect: Disconnect from the underlying data source, performing any
* necessary clean up operations in the process.
* - request: Satisfy a request for data. The format that this request takes
* will likely differ across implementations. An array of further
* options may be provided as an optional second argument. As a
* concrete example, an SQL-like data source may support string
* requests like "SELECT * FROM foo WHERE bar='baz'". The
* response from this call must be an ApplicationDataResponse object
* containing the (possibly multidimensional) array of response info.
* - command: Send a command to the underlying data source. As with request,
* the format that this command takes will likely differ across
* implementations. As a concrete example, an SQL-like data source
* may support string commands like "UPDATE foo set bar='baz'".
* Command should not be expected to return a value, other than
* possibly true/false to indicate the success of the call.
*
*
* Framework implementations of common data providers can be found in:
* {LIB}/classes/dataProviders and should be named FooDataProvider.class.php.
* Framework data providers can be invoked by doing:
* $app->GetDataProvider('FooDataProvider');
*
* Custom data providers should be placed in:
* {HOME}/classes/dataProviders and should be named FooDataProvider.class.php.
* Custom data providers can be invoked by doing:
* $app->GetDataProvider('foo',true); // true --> custom
*
* @author ahart
*
*/
interface Org_Apache_Oodt_Balance_Interfaces_IApplicationDataProvider {
/**
* Constructor - Instantiate the provider but do not yet connect
* to the underlying data source.
*
* @param $options array An optional set of configuration values
*/
public function __construct($options = array());
/**
* Initiate a connection to the underlying data source
*
* @param $options array An optional set of configuration values
* @return boolean True or false depending on the result
*/
public function connect($options = array());
/**
* Disconnect from the underlying data source and perform any
* cleanup operations necessary.
*
* @param $options array An optional set of configuration values
* @return unknown_type True or false depending on the result
*/
public function disconnect($options = array());
/**
* Request data from the underlying data source.
*
* @param $request mixed The request itself, usually a string. The nature
* of the request is necessarily implementation
* specific and will vary across providers. For a
* SQL-like relational provider, this will likely be
* a "SELECT ..." string.
* @param $options array An array of options to configure the request.
* These will be implementation-specific and
* therefore will likely differ across providers.
* @return ApplicationDataResponse The resulting data retrieved
*/
public function request($request,$options = array());
/**
* Send a command to the underlying data source.
*
* @param $command mixed The command itself, usually a string. The nature
* of the command is necessarily implementation
* specific and will vary across providers. For a
* SQL-like relational provider, this will likely be
* a "UPDATE ...", or "CREATE ..." string.
* @param $options array An array of options to configure the command.
* These will be implementation-specific and
* therefore will likely differ across providers.
* @return boolean True or false depending on the success of the command
*/
public function command($command,$options = array());
}