| /* |
| * Copyright 2009-2011 by The Regents of the University of California |
| * Licensed 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 from |
| * |
| * 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. |
| */ |
| package edu.uci.ics.asterix.external.data.adapter.api; |
| |
| import java.io.Serializable; |
| import java.util.Map; |
| |
| import edu.uci.ics.asterix.om.types.IAType; |
| import edu.uci.ics.hyracks.algebricks.common.constraints.AlgebricksPartitionConstraint; |
| import edu.uci.ics.hyracks.api.context.IHyracksTaskContext; |
| |
| /** |
| * A super interface implemented by a data source adapter. An adapter can be a |
| * pull based or push based. This interface provides all common APIs that need |
| * to be implemented by each adapter irrespective of the the kind of |
| * adapter(pull or push). |
| */ |
| public interface IDatasourceAdapter extends Serializable { |
| |
| /** |
| * Represents the kind of data exchange that happens between the adapter and |
| * the external data source. The data exchange can be either pull based or |
| * push based. In the former case (pull), the request for data transfer is |
| * initiated by the adapter. In the latter case (push) the adapter is |
| * required to submit an initial request to convey intent for data. |
| * Subsequently all data transfer requests are initiated by the external |
| * data source. |
| */ |
| public enum AdapterDataFlowType { |
| PULL, |
| PUSH |
| } |
| |
| /** |
| * An adapter can be used to read from an external data source and may also |
| * allow writing to the external data source. This enum type indicates the |
| * kind of operations supported by the adapter. |
| * |
| * @caller Compiler uses this method to assert the validity of an operation |
| * on an external dataset. The type of adapter associated with an |
| * external dataset determines the set of valid operations allowed |
| * on the dataset. |
| */ |
| public enum AdapterType { |
| READ, |
| WRITE, |
| READ_WRITE |
| } |
| |
| /** |
| * An adapter can be a pull or a push based adapter. This method returns the |
| * kind of adapter, that is whether it is a pull based adapter or a push |
| * based adapter. |
| * |
| * @caller Compiler or wrapper operator: Compiler uses this API to choose |
| * the right wrapper (push-based) operator that wraps around the |
| * adapter and provides an iterator interface. If we decide to form |
| * a single operator that handles both pull and push based adapter |
| * kinds, then this method will be used by the wrapper operator for |
| * switching between the logic for interacting with a pull based |
| * adapter versus a push based adapter. |
| * @return AdapterDataFlowType |
| */ |
| public AdapterDataFlowType getAdapterDataFlowType(); |
| |
| /** |
| * Returns the type of adapter indicating if the adapter can be used for |
| * reading from an external data source or writing to an external data |
| * source or can be used for both purposes. |
| * |
| * @Caller: Compiler: The compiler uses this API to verify if an operation |
| * is supported by the adapter. For example, an write query against |
| * an external dataset will not compile successfully if the |
| * external dataset was declared with a read_only adapter. |
| * @see AdapterType |
| * @return |
| */ |
| public AdapterType getAdapterType(); |
| |
| /** |
| * Each adapter instance is configured with a set of parameters that are |
| * key-value pairs. When creating an external or a feed dataset, an adapter |
| * instance is used in conjunction with a set of configuration parameters |
| * for the adapter instance. The configuration parameters are stored |
| * internally with the adapter and can be retrieved using this API. |
| * |
| * @param propertyKey |
| * @return String the value corresponding to the configuration parameter |
| * represented by the key- attributeKey. |
| */ |
| public String getAdapterProperty(String propertyKey); |
| |
| /** |
| * Allows setting a configuration property of the adapter with a specified |
| * value. |
| * |
| * @caller Used by the wrapper operator to modify the behavior of the |
| * adapter, if required. |
| * @param property |
| * the property to be set |
| * @param value |
| * the value for the property |
| */ |
| public void setAdapterProperty(String property, String value); |
| |
| /** |
| * Configures the IDatasourceAdapter instance. |
| * |
| * @caller Scenario 1) Called during compilation of DDL statement that |
| * creates a Feed dataset and associates the adapter with the |
| * dataset. The (key,value) configuration parameters provided as |
| * part of the DDL statement are collected by the compiler and |
| * passed on to this method. The adapter may as part of |
| * configuration connect with the external data source and determine |
| * the IAType associated with data residing with the external |
| * datasource. |
| * Scenario 2) An adapter instance is created by an ASTERIX operator |
| * that wraps around the adapter instance. The operator, as part of |
| * its initialization invokes the configure method. The (key,value) |
| * configuration parameters are passed on to the operator by the |
| * compiler. Subsequent to the invocation, the wrapping operator |
| * obtains the partition constraints (if any). In addition, in the |
| * case of a read adapter, the wrapping operator obtains the output |
| * ASTERIX type associated with the data that will be output from |
| * the adapter. |
| * @param arguments |
| * A map with key-value pairs that contains the configuration |
| * parameters for the adapter. The arguments are obtained from |
| * the metadata. Recall that the DDL to create an external |
| * dataset or a feed dataset requires using an adapter and |
| * providing all arguments as a set of (key,value) pairs. These |
| * arguments are put into the metadata. |
| */ |
| public void configure(Map<String, String> arguments, IAType atype) |
| throws Exception; |
| |
| /** |
| * Returns a list of partition constraints. A partition constraint can be a |
| * requirement to execute at a particular location or could be cardinality |
| * constraints indicating the number of instances that need to run in |
| * parallel. example, a IDatasourceAdapter implementation written for data |
| * residing on the local file system of a node cannot run on any other node |
| * and thus has a location partition constraint. The location partition |
| * constraint can be expressed as a node IP address or a node controller id. |
| * In the former case, the IP address is translated to a node controller id |
| * running on the node with the given IP address. |
| * |
| * @Caller The wrapper operator configures its partition constraints from |
| * the constraints obtained from the adapter. |
| */ |
| public AlgebricksPartitionConstraint getPartitionConstraint(); |
| |
| /** |
| * Allows the adapter to establish connection with the external data source |
| * expressing intent for data and providing any configuration parameters |
| * required by the external data source for the transfer of data. This |
| * method does not result in any data transfer, but is a prerequisite for |
| * any subsequent data transfer to happen between the external data source |
| * and the adapter. |
| * |
| * @caller This method is called by the wrapping ASTERIX operator that |
| * @param ctx |
| * @throws Exception |
| */ |
| public void initialize(IHyracksTaskContext ctx) throws Exception; |
| } |