001    /*
002    // $Id: XmlaOlap4jCache.java 229 2009-05-08 19:11:29Z jhyde $
003    // This software is subject to the terms of the Eclipse Public License v1.0
004    // Agreement, available at the following URL:
005    // http://www.eclipse.org/legal/epl-v10.html.
006    // Copyright (C) 2008-2009 Julian Hyde
007    // All Rights Reserved.
008    // You must accept the terms of that agreement to use this software.
009    */
010    package org.olap4j.driver.xmla.cache;
011    
012    import java.net.URL;
013    import java.util.Map;
014    
015    /**
016     * XMLA driver cache. Implementations will have to declare those methods.
017     *
018     * <p>The XMLA driver will call the cache before each SOAP request to see
019     * if it wasn't sent previously and if a SOAP response doesn't already
020     * exist in it.
021     *
022     * <p>Any implementations have to declare a constructor which takes a String
023     * as a parameter. This string value is the unique name of the connection
024     * which triggered the request.
025     *
026     * @author Luc Boudreau
027     * @version $Id: XmlaOlap4jCache.java 229 2009-05-08 19:11:29Z jhyde $
028     */
029    public interface XmlaOlap4jCache {
030    
031        /**
032         * Fetches a SOAP response from the cache. Returns null
033         * if there are no cached response corresponding to the SOAP
034         * message and the URL.
035         *
036         * @param id The connection unique name which called this cache.
037         * @param url The URL where the SOAP message was sent.
038         * @param request The SOAP complete message.
039         *
040         * @throws XmlaOlap4jInvalidStateException when
041         * operations to the cache are performed but it hasn't been initialized.
042         * Make sure you call the setParameters method.
043         *
044         * @return The SOAP response, null if there are no corresponding
045         * response in the cache.
046         */
047        public byte[] get(
048            String id,
049            URL url,
050            byte[] request)
051            throws XmlaOlap4jInvalidStateException;
052    
053        /**
054         * Adds a SOAP response to the cache. It has to be relative to the
055         * URL of the SOAP service.
056         *
057         * @param id The connection unique name which called this cache.
058         * @param url The URL of the SOAP endpoint.
059         * @param request The full SOAP message from which we want to cache its
060         * response.
061         * @param response The response to cache.
062         *
063         * @throws XmlaOlap4jInvalidStateException when
064         * operations to the cache are performed but it hasn't been initialized.
065         * Make sure you call the setParameters method.
066         */
067        public void put(
068            String id,
069            URL url,
070            byte[] request,
071            byte[] response)
072            throws XmlaOlap4jInvalidStateException;
073    
074        /**
075         * Tells the cache to flush all cached entries.
076         */
077        public void flushCache();
078    
079        /**
080         * Convenience method to receive custom properties.
081         *
082         * <p>The XMLA driver takes cache properties as
083         * "<code>Cache.[property name]=[value]</code>" in its JDBC url. All those
084         * properties should be striped of their "<code>Cache.</code>" prefix and
085         * sent to this method as the properties parameter.
086         *
087         * <p>Also, the complete config map of the current connection
088         * should be passed as the config parameter.
089         *
090         * @param config The complete configuration parameters which were used to
091         * create the current connection.
092         * @param props The properties received from the JDBC url.
093         * @return Returns a string object which gives a reference id to the
094         * caller for future use. This id has to be passed along with any future
095         * get and put requests.
096         */
097        public String setParameters(
098            Map<String, String> config,
099            Map<String, String> props);
100    }
101    
102    // End XmlaOlap4jCache.java