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