001/*
002// $Id: XmlaOlap4jCache.java 482 2012-01-05 23:27:27Z jhyde $
003//
004// Licensed to Julian Hyde under one or more contributor license
005// agreements. See the NOTICE file distributed with this work for
006// additional information regarding copyright ownership.
007//
008// Julian Hyde licenses this file to you under the Apache License,
009// Version 2.0 (the "License"); you may not use this file except in
010// compliance with the License. You may obtain a copy of the License at:
011//
012// http://www.apache.org/licenses/LICENSE-2.0
013//
014// Unless required by applicable law or agreed to in writing, software
015// distributed under the License is distributed on an "AS IS" BASIS,
016// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017// See the License for the specific language governing permissions and
018// limitations under the License.
019*/
020package org.olap4j.driver.xmla.cache;
021
022import org.olap4j.OlapException;
023
024import java.net.URL;
025import java.util.Map;
026
027/**
028 * XMLA driver cache. Implementations will have to declare those methods.
029 *
030 * <p>The XMLA driver will call the cache before each SOAP request to see
031 * if it wasn't sent previously and if a SOAP response doesn't already
032 * exist in it.
033 *
034 * <p>Any implementations have to declare a constructor which takes a String
035 * as a parameter. This string value is the unique name of the connection
036 * which triggered the request.
037 *
038 * @author Luc Boudreau
039 * @version $Id: XmlaOlap4jCache.java 482 2012-01-05 23:27:27Z jhyde $
040 */
041public interface XmlaOlap4jCache {
042
043    /**
044     * Fetches a SOAP response from the cache. Returns null
045     * if there are no cached response corresponding to the SOAP
046     * message and the URL.
047     *
048     * @param id The connection unique name which called this cache.
049     * @param url The URL where the SOAP message was sent.
050     * @param request The SOAP complete message.
051     *
052     * @throws OlapException when operations to the cache are
053     * performed but it hasn't been initialized. Make sure you
054     * call the setParameters(Map, Map) method.
055     *
056     * @return The SOAP response, null if there are no corresponding
057     * response in the cache.
058     */
059    public byte[] get(
060        String id,
061        URL url,
062        byte[] request)
063        throws OlapException;
064
065    /**
066     * Adds a SOAP response to the cache. It has to be relative to the
067     * URL of the SOAP service.
068     *
069     * @param id The connection unique name which called this cache.
070     * @param url The URL of the SOAP endpoint.
071     * @param request The full SOAP message from which we want to cache its
072     * response.
073     * @param response The response to cache.
074     *
075     * @throws OlapException when operations to the cache are
076     * performed but it hasn't been initialized. Make sure you
077     * call the setParameters(Map, Map) method.
078     */
079    public void put(
080        String id,
081        URL url,
082        byte[] request,
083        byte[] response)
084        throws OlapException;
085
086    /**
087     * Tells the cache to flush all cached entries.
088     */
089    public void flushCache();
090
091    /**
092     * Convenience method to receive custom properties.
093     *
094     * <p>The XMLA driver takes cache properties as
095     * "<code>Cache.[property name]=[value]</code>" in its JDBC url. All those
096     * properties should be striped of their "<code>Cache.</code>" prefix and
097     * sent to this method as the props parameter.
098     *
099     * <p>Also, the complete  map of the current connection
100     * should be passed as the config parameter.
101     *
102     * @param config The complete configuration parameters which were used to
103     * create the current connection.
104     * @param props The properties received from the JDBC url.
105     * @return Returns a string object which gives a reference id to the
106     * caller for future use. This id has to be passed along with any future
107     * get and put requests.
108     */
109    public String setParameters(
110        Map<String, String> config,
111        Map<String, String> props);
112}
113
114// End XmlaOlap4jCache.java