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    */
020    package org.olap4j.driver.xmla.cache;
021    
022    import org.olap4j.OlapException;
023    
024    import java.net.URL;
025    import 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     */
041    public 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