/usr/share/doc/libolap4j-java/api/src-html/org/olap4j/CellSetListener.AxisChange.html is in libolap4j-java-doc 1.0.1.500-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<title>Source code</title>
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
</head>
<body>
<div class="sourceContainer">
<pre><span class="sourceLineNo">001</span>/*<a name="line.1"></a>
<span class="sourceLineNo">002</span>// $Id: CellSetListener.java 482 2012-01-05 23:27:27Z jhyde $<a name="line.2"></a>
<span class="sourceLineNo">003</span>//<a name="line.3"></a>
<span class="sourceLineNo">004</span>// Licensed to Julian Hyde under one or more contributor license<a name="line.4"></a>
<span class="sourceLineNo">005</span>// agreements. See the NOTICE file distributed with this work for<a name="line.5"></a>
<span class="sourceLineNo">006</span>// additional information regarding copyright ownership.<a name="line.6"></a>
<span class="sourceLineNo">007</span>//<a name="line.7"></a>
<span class="sourceLineNo">008</span>// Julian Hyde licenses this file to you under the Apache License,<a name="line.8"></a>
<span class="sourceLineNo">009</span>// Version 2.0 (the "License"); you may not use this file except in<a name="line.9"></a>
<span class="sourceLineNo">010</span>// compliance with the License. You may obtain a copy of the License at:<a name="line.10"></a>
<span class="sourceLineNo">011</span>//<a name="line.11"></a>
<span class="sourceLineNo">012</span>// http://www.apache.org/licenses/LICENSE-2.0<a name="line.12"></a>
<span class="sourceLineNo">013</span>//<a name="line.13"></a>
<span class="sourceLineNo">014</span>// Unless required by applicable law or agreed to in writing, software<a name="line.14"></a>
<span class="sourceLineNo">015</span>// distributed under the License is distributed on an "AS IS" BASIS,<a name="line.15"></a>
<span class="sourceLineNo">016</span>// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<a name="line.16"></a>
<span class="sourceLineNo">017</span>// See the License for the specific language governing permissions and<a name="line.17"></a>
<span class="sourceLineNo">018</span>// limitations under the License.<a name="line.18"></a>
<span class="sourceLineNo">019</span>*/<a name="line.19"></a>
<span class="sourceLineNo">020</span>package org.olap4j;<a name="line.20"></a>
<span class="sourceLineNo">021</span><a name="line.21"></a>
<span class="sourceLineNo">022</span>import java.util.List;<a name="line.22"></a>
<span class="sourceLineNo">023</span><a name="line.23"></a>
<span class="sourceLineNo">024</span>/**<a name="line.24"></a>
<span class="sourceLineNo">025</span> * Listener interface for receiving events when the contents of a<a name="line.25"></a>
<span class="sourceLineNo">026</span> * {@link CellSet} have changed.<a name="line.26"></a>
<span class="sourceLineNo">027</span> *<a name="line.27"></a>
<span class="sourceLineNo">028</span> * <p>NOTE: This functionality is experimental and is subject to change or<a name="line.28"></a>
<span class="sourceLineNo">029</span> * removal without notice.<a name="line.29"></a>
<span class="sourceLineNo">030</span> *<a name="line.30"></a>
<span class="sourceLineNo">031</span> * <p>The client can ask the server to provide the listener with a specific<a name="line.31"></a>
<span class="sourceLineNo">032</span> * {@link Granularity granularity} of events, but the server can decline to<a name="line.32"></a>
<span class="sourceLineNo">033</span> * provide that granularity.<a name="line.33"></a>
<span class="sourceLineNo">034</span> *<a name="line.34"></a>
<span class="sourceLineNo">035</span> * <p>Fine granularity deals with changes such as cell values changing (and<a name="line.35"></a>
<span class="sourceLineNo">036</span> * reports the before and after value, before and after formatted value),<a name="line.36"></a>
<span class="sourceLineNo">037</span> * positions being deleted, positions being changed.<a name="line.37"></a>
<span class="sourceLineNo">038</span> *<a name="line.38"></a>
<span class="sourceLineNo">039</span> * <p>When an atomic change happens on the server (say a cache flush, if the<a name="line.39"></a>
<span class="sourceLineNo">040</span> * server is mondrian) then an event will arrive on the client containing all of<a name="line.40"></a>
<span class="sourceLineNo">041</span> * those changes. Although {@link CellSetChange#getCellChanges} and<a name="line.41"></a>
<span class="sourceLineNo">042</span> * {@link CellSetChange#getAxisChanges} return lists, the client should assume<a name="line.42"></a>
<span class="sourceLineNo">043</span> * that all of the events in these lists simultaneously.<a name="line.43"></a>
<span class="sourceLineNo">044</span> *<a name="line.44"></a>
<span class="sourceLineNo">045</span> * <p>At any point, the server is free to throw up its hands and say 'there are<a name="line.45"></a>
<span class="sourceLineNo">046</span> * too many changes' by sending null values for {@code getCellChanges} or<a name="line.46"></a>
<span class="sourceLineNo">047</span> * {@code getAxisChanges}. This prevents situations where there are huge numbers<a name="line.47"></a>
<span class="sourceLineNo">048</span> * of changes that might overwhelm the server, the network link, or the client,<a name="line.48"></a>
<span class="sourceLineNo">049</span> * such as might happen if a large axis is re-sorted.<a name="line.49"></a>
<span class="sourceLineNo">050</span> *<a name="line.50"></a>
<span class="sourceLineNo">051</span> * <p>The client should always be ready for that to happen (even for providers<a name="line.51"></a>
<span class="sourceLineNo">052</span> * that claim to provide fine granularity events), and should re-execute the<a name="line.52"></a>
<span class="sourceLineNo">053</span> * query to get the cell set. In fact, we recommend that clients re-execute the<a name="line.53"></a>
<span class="sourceLineNo">054</span> * query to get a new cellset whenever they get an event. Then the client can<a name="line.54"></a>
<span class="sourceLineNo">055</span> * use the details in the event to highlight cells that have changed.<a name="line.55"></a>
<span class="sourceLineNo">056</span> *<a name="line.56"></a>
<span class="sourceLineNo">057</span> * <h3>Notes for implementors</h3><a name="line.57"></a>
<span class="sourceLineNo">058</span> *<a name="line.58"></a>
<span class="sourceLineNo">059</span> * <p>The purpose of registering a listener before creating a cell set is to<a name="line.59"></a>
<span class="sourceLineNo">060</span> * ensure that no events "leak out" between creating a cell set and registering<a name="line.60"></a>
<span class="sourceLineNo">061</span> * a listener, or while a statement is being re-executed to produce a new cell<a name="line.61"></a>
<span class="sourceLineNo">062</span> * set.<a name="line.62"></a>
<span class="sourceLineNo">063</span> *<a name="line.63"></a>
<span class="sourceLineNo">064</span> * <p>The {@link #cellSetOpened(CellSet)} and {@link #cellSetClosed(CellSet)}<a name="line.64"></a>
<span class="sourceLineNo">065</span> * methods are provided so that the listener knows what is going on when a<a name="line.65"></a>
<span class="sourceLineNo">066</span> * statement is re-executed. In particular, suppose a statement receives an<a name="line.66"></a>
<span class="sourceLineNo">067</span> * change event decides to re-execute. The listener is attached to the<a name="line.67"></a>
<span class="sourceLineNo">068</span> * statement, so receives notifications about both old and new cell sets. The<a name="line.68"></a>
<span class="sourceLineNo">069</span> * driver implicitls closes the previous cell set and calls<a name="line.69"></a>
<span class="sourceLineNo">070</span> * {@code cellSetClosed}, then calls {@code cellSetOpened} with the new cell<a name="line.70"></a>
<span class="sourceLineNo">071</span> * set.<a name="line.71"></a>
<span class="sourceLineNo">072</span> *<a name="line.72"></a>
<span class="sourceLineNo">073</span> * <p>If changes are occurring regularly on the server, there will soon be a<a name="line.73"></a>
<span class="sourceLineNo">074</span> * call to {@link #cellSetChanged}. It is important to note that this event<a name="line.74"></a>
<span class="sourceLineNo">075</span> * contains only changes that have occurred since the new cell set was opened.<a name="line.75"></a>
<span class="sourceLineNo">076</span> *<a name="line.76"></a>
<span class="sourceLineNo">077</span> * <p>The granularity parameter is provided to {@link OlapStatement#addListener}<a name="line.77"></a>
<span class="sourceLineNo">078</span> * for the server's benefit. If granularity is only {@link Granularity#COARSE},<a name="line.78"></a>
<span class="sourceLineNo">079</span> * the server may be able to store less information in order to track the cell<a name="line.79"></a>
<span class="sourceLineNo">080</span> * set.<a name="line.80"></a>
<span class="sourceLineNo">081</span> *<a name="line.81"></a>
<span class="sourceLineNo">082</span> * @version $Id: CellSetListener.java 482 2012-01-05 23:27:27Z jhyde $<a name="line.82"></a>
<span class="sourceLineNo">083</span> */<a name="line.83"></a>
<span class="sourceLineNo">084</span>public interface CellSetListener {<a name="line.84"></a>
<span class="sourceLineNo">085</span><a name="line.85"></a>
<span class="sourceLineNo">086</span> /**<a name="line.86"></a>
<span class="sourceLineNo">087</span> * Invoked when a cell set is opened.<a name="line.87"></a>
<span class="sourceLineNo">088</span> *<a name="line.88"></a>
<span class="sourceLineNo">089</span> * @param cellSet Cell set<a name="line.89"></a>
<span class="sourceLineNo">090</span> */<a name="line.90"></a>
<span class="sourceLineNo">091</span> void cellSetOpened(CellSet cellSet);<a name="line.91"></a>
<span class="sourceLineNo">092</span><a name="line.92"></a>
<span class="sourceLineNo">093</span> /**<a name="line.93"></a>
<span class="sourceLineNo">094</span> * Invoked when a cell set is closed.<a name="line.94"></a>
<span class="sourceLineNo">095</span> *<a name="line.95"></a>
<span class="sourceLineNo">096</span> * @param cellSet Cell set<a name="line.96"></a>
<span class="sourceLineNo">097</span> */<a name="line.97"></a>
<span class="sourceLineNo">098</span> void cellSetClosed(CellSet cellSet);<a name="line.98"></a>
<span class="sourceLineNo">099</span><a name="line.99"></a>
<span class="sourceLineNo">100</span> /**<a name="line.100"></a>
<span class="sourceLineNo">101</span> * Invoked when a cell set has changed.<a name="line.101"></a>
<span class="sourceLineNo">102</span> *<a name="line.102"></a>
<span class="sourceLineNo">103</span> * @param cellSetChange Change descriptor<a name="line.103"></a>
<span class="sourceLineNo">104</span> */<a name="line.104"></a>
<span class="sourceLineNo">105</span> void cellSetChanged(CellSetChange cellSetChange);<a name="line.105"></a>
<span class="sourceLineNo">106</span><a name="line.106"></a>
<span class="sourceLineNo">107</span> /**<a name="line.107"></a>
<span class="sourceLineNo">108</span> * Granularity of notifications that should be sent to a cellset listener.<a name="line.108"></a>
<span class="sourceLineNo">109</span> */<a name="line.109"></a>
<span class="sourceLineNo">110</span> enum Granularity {<a name="line.110"></a>
<span class="sourceLineNo">111</span> FINE,<a name="line.111"></a>
<span class="sourceLineNo">112</span> COARSE<a name="line.112"></a>
<span class="sourceLineNo">113</span> }<a name="line.113"></a>
<span class="sourceLineNo">114</span><a name="line.114"></a>
<span class="sourceLineNo">115</span> /**<a name="line.115"></a>
<span class="sourceLineNo">116</span> * Description of changes that have occurred to the cell set.<a name="line.116"></a>
<span class="sourceLineNo">117</span> */<a name="line.117"></a>
<span class="sourceLineNo">118</span> interface CellSetChange {<a name="line.118"></a>
<span class="sourceLineNo">119</span> /**<a name="line.119"></a>
<span class="sourceLineNo">120</span> * Returns the cell set affected by this change.<a name="line.120"></a>
<span class="sourceLineNo">121</span> *<a name="line.121"></a>
<span class="sourceLineNo">122</span> * @return Cell set affected by this change.<a name="line.122"></a>
<span class="sourceLineNo">123</span> */<a name="line.123"></a>
<span class="sourceLineNo">124</span> CellSet getCellSet();<a name="line.124"></a>
<span class="sourceLineNo">125</span><a name="line.125"></a>
<span class="sourceLineNo">126</span> /**<a name="line.126"></a>
<span class="sourceLineNo">127</span> * Returns a list of cells that have changed, or null if the server<a name="line.127"></a>
<span class="sourceLineNo">128</span> * cannot provide detailed changes.<a name="line.128"></a>
<span class="sourceLineNo">129</span> *<a name="line.129"></a>
<span class="sourceLineNo">130</span> * <p>The server is always at liberty to provide a {@code CellSetChange}<a name="line.130"></a>
<span class="sourceLineNo">131</span> * without a detailed list of changes, even if<a name="line.131"></a>
<span class="sourceLineNo">132</span> * {@link Granularity#COARSE} was specified when the listener was<a name="line.132"></a>
<span class="sourceLineNo">133</span> * attached. Here are some typical reasons:<ul><a name="line.133"></a>
<span class="sourceLineNo">134</span> *<a name="line.134"></a>
<span class="sourceLineNo">135</span> * <li>If there are very many changes. (Transmitting these changes over<a name="line.135"></a>
<span class="sourceLineNo">136</span> * the network would be costly, and the user interface also might<a name="line.136"></a>
<span class="sourceLineNo">137</span> * struggle to redisplay so many cells.)<a name="line.137"></a>
<span class="sourceLineNo">138</span> *<a name="line.138"></a>
<span class="sourceLineNo">139</span> * <li>If the axes have changed significantly. (If an axis position has<a name="line.139"></a>
<span class="sourceLineNo">140</span> * changed, all of the cells at that position will necssarily have<a name="line.140"></a>
<span class="sourceLineNo">141</span> * changed.)<a name="line.141"></a>
<span class="sourceLineNo">142</span> *<a name="line.142"></a>
<span class="sourceLineNo">143</span> * <li>If the client did not ask for detailed changes<a name="line.143"></a>
<span class="sourceLineNo">144</span> *<a name="line.144"></a>
<span class="sourceLineNo">145</span> * <li>If the the provider is not capable of giving detailed changes.<a name="line.145"></a>
<span class="sourceLineNo">146</span> * </ul><a name="line.146"></a>
<span class="sourceLineNo">147</span> */<a name="line.147"></a>
<span class="sourceLineNo">148</span> List<CellChange> getCellChanges();<a name="line.148"></a>
<span class="sourceLineNo">149</span><a name="line.149"></a>
<span class="sourceLineNo">150</span> /**<a name="line.150"></a>
<span class="sourceLineNo">151</span> * Returns a list of axis changes, or null if server cannot provide<a name="line.151"></a>
<span class="sourceLineNo">152</span> * detailed changes.<a name="line.152"></a>
<span class="sourceLineNo">153</span> *<a name="line.153"></a>
<span class="sourceLineNo">154</span> * <p>The reasons why this method returns null are similar to the<a name="line.154"></a>
<span class="sourceLineNo">155</span> * reasons why {@link #getCellChanges()} returns null.<a name="line.155"></a>
<span class="sourceLineNo">156</span> *<a name="line.156"></a>
<span class="sourceLineNo">157</span> * @return List of changes to positions on axes, or null if the server<a name="line.157"></a>
<span class="sourceLineNo">158</span> * cannot provide detailed changes.<a name="line.158"></a>
<span class="sourceLineNo">159</span> */<a name="line.159"></a>
<span class="sourceLineNo">160</span> List<AxisChange> getAxisChanges();<a name="line.160"></a>
<span class="sourceLineNo">161</span> }<a name="line.161"></a>
<span class="sourceLineNo">162</span><a name="line.162"></a>
<span class="sourceLineNo">163</span> /**<a name="line.163"></a>
<span class="sourceLineNo">164</span> * Description of a change to a particular {@link Cell}; part of a<a name="line.164"></a>
<span class="sourceLineNo">165</span> * {@link CellSetChange}.<a name="line.165"></a>
<span class="sourceLineNo">166</span> */<a name="line.166"></a>
<span class="sourceLineNo">167</span> interface CellChange {<a name="line.167"></a>
<span class="sourceLineNo">168</span> /**<a name="line.168"></a>
<span class="sourceLineNo">169</span> * Returns the cell before the change.<a name="line.169"></a>
<span class="sourceLineNo">170</span> */<a name="line.170"></a>
<span class="sourceLineNo">171</span> Cell getBeforeCell();<a name="line.171"></a>
<span class="sourceLineNo">172</span><a name="line.172"></a>
<span class="sourceLineNo">173</span> /**<a name="line.173"></a>
<span class="sourceLineNo">174</span> * Returns the cell after the change.<a name="line.174"></a>
<span class="sourceLineNo">175</span> */<a name="line.175"></a>
<span class="sourceLineNo">176</span> Cell getAfterCell();<a name="line.176"></a>
<span class="sourceLineNo">177</span> }<a name="line.177"></a>
<span class="sourceLineNo">178</span><a name="line.178"></a>
<span class="sourceLineNo">179</span> /**<a name="line.179"></a>
<span class="sourceLineNo">180</span> * Description of a change to a particular {@link CellSetAxis}; part of a<a name="line.180"></a>
<span class="sourceLineNo">181</span> * {@link CellSetChange}.<a name="line.181"></a>
<span class="sourceLineNo">182</span> */<a name="line.182"></a>
<span class="sourceLineNo">183</span> interface AxisChange {<a name="line.183"></a>
<span class="sourceLineNo">184</span> /**<a name="line.184"></a>
<span class="sourceLineNo">185</span> * Returns the axis affected by this change.<a name="line.185"></a>
<span class="sourceLineNo">186</span> *<a name="line.186"></a>
<span class="sourceLineNo">187</span> * @return Axis affected by this change<a name="line.187"></a>
<span class="sourceLineNo">188</span> */<a name="line.188"></a>
<span class="sourceLineNo">189</span> CellSetAxis getAxis();<a name="line.189"></a>
<span class="sourceLineNo">190</span><a name="line.190"></a>
<span class="sourceLineNo">191</span> /**<a name="line.191"></a>
<span class="sourceLineNo">192</span> * Returns the position before the change. Null if the change created a<a name="line.192"></a>
<span class="sourceLineNo">193</span> * new position.<a name="line.193"></a>
<span class="sourceLineNo">194</span> *<a name="line.194"></a>
<span class="sourceLineNo">195</span> * @return Position before the change, or null if the position is newly<a name="line.195"></a>
<span class="sourceLineNo">196</span> * created<a name="line.196"></a>
<span class="sourceLineNo">197</span> */<a name="line.197"></a>
<span class="sourceLineNo">198</span> Position getBeforePosition();<a name="line.198"></a>
<span class="sourceLineNo">199</span><a name="line.199"></a>
<span class="sourceLineNo">200</span> /**<a name="line.200"></a>
<span class="sourceLineNo">201</span> * Returns the position after the change. Null if the change deleted<a name="line.201"></a>
<span class="sourceLineNo">202</span> * this position.<a name="line.202"></a>
<span class="sourceLineNo">203</span> *<a name="line.203"></a>
<span class="sourceLineNo">204</span> * @return Position after the change, or null if the position is deleted<a name="line.204"></a>
<span class="sourceLineNo">205</span> */<a name="line.205"></a>
<span class="sourceLineNo">206</span> Position getAfterPosition();<a name="line.206"></a>
<span class="sourceLineNo">207</span> }<a name="line.207"></a>
<span class="sourceLineNo">208</span>}<a name="line.208"></a>
<span class="sourceLineNo">209</span><a name="line.209"></a>
<span class="sourceLineNo">210</span>// End CellSetListener.java<a name="line.210"></a>
</pre>
</div>
</body>
</html>
|