001/** 002 * MutableAccumulator.java 003 * 004 * Copyright (c) 2004-2012, Nicole C. Tedesco. All rights reserved. 005 * 006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 007 * use this file except in compliance with the License. You may obtain a copy of 008 * 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, WITHOUT 014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 015 * License for the specific language governing permissions and limitations under 016 * the License. 017 */ 018 019package net.sf.jaccumulator; 020 021import java.math.BigDecimal; 022import java.math.BigInteger; 023import java.util.NoSuchElementException; 024 025import net.sf.jaccumulator.primitives.MutablePrimitive; 026import net.sf.jaccumulator.primitives.Primitive; 027 028/** 029 * A write-only {@link Accumulator} 030 * 031 * @param <ACCUMULATOR> 032 * this {@link Accumulator} type 033 * @since JAccumulator 4.0 034 * @author Nicole Tedesco (<a 035 * href="mailto:nicole@tedesco.name">nicole@tedesco.name</a>) 036 */ 037public interface MutableAccumulator<ACCUMULATOR extends MutableAccumulator<ACCUMULATOR>> 038 extends 039 MutablePrimitive<ACCUMULATOR> 040{ 041 /** 042 * Remove and return the last (highest order) member from this Accumulator's 043 * {@link SealedAccumulator#members() relationship} collection 044 * 045 * @return this Accumulator (facilitates operations chaining) 046 * 047 * @throws UnsupportedOperationException 048 * this Accumulator's relationship collection could not changed 049 * @throws IllegalStateException 050 * this Accumulator's relationship collection could not be changed 051 * at this time 052 * @throws NoSuchElementException 053 * this Accumulator's relationship collection was empty 054 */ 055 public Accumulator<?> pop() 056 throws UnsupportedOperationException, 057 IllegalStateException, 058 NoSuchElementException; 059 060 /** 061 * A convenience function to append a new member to the end of this 062 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 063 * collection 064 * 065 * @param aMember 066 * a new relationship 067 * @return this Accumulator (facilitates operations chaining) 068 * 069 * @throws UnsupportedOperationException 070 * this Accumulator's relationship collection could not be changed 071 * @throws NullPointerException 072 * a {@code null} value was provided where none was expected 073 * @throws IllegalStateException 074 * this Accumulator's relationship collection could not be changed 075 * at this time 076 */ 077 public ACCUMULATOR push( final Accumulator<?> aMember ) 078 throws UnsupportedOperationException, 079 NullPointerException, 080 IllegalStateException; 081 082 /** 083 * A convenience function to append a new keyed (named) member to the end of 084 * this Accumulator's {@link SealedSealedAccumulator#members() relationship} 085 * collection 086 * 087 * @param aKey 088 * a new key (name) 089 * @param aMember 090 * a new relationship 091 * @return this Accumulator (facilitates operations chaining) 092 * 093 * @throws UnsupportedOperationException 094 * this Accumulator's relationship collection could not changed 095 * @throws NullPointerException 096 * a {@code null} value was provided where none was expected 097 * @throws IllegalStateException 098 * this Accumulator's relationship collection could not be changed 099 * at this time 100 */ 101 public ACCUMULATOR push( 102 final Accumulator<?> aKey, 103 final Accumulator<?> aMember ) 104 throws UnsupportedOperationException, 105 NullPointerException, 106 IllegalStateException; 107 108 /** 109 * A convenience function to append a new member to the end of this 110 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 111 * collection 112 * 113 * @param aMember 114 * a new relationship 115 * @return this Accumulator (facilitates operations chaining) 116 * 117 * @throws UnsupportedOperationException 118 * this Accumulator's relationship collection could not be changed 119 * @throws NullPointerException 120 * a {@code null} value was provided where none was expected 121 * @throws IllegalStateException 122 * this Accumulator's relationship collection could not be changed 123 * at this time 124 */ 125 public ACCUMULATOR push( final BigDecimal aMember ) 126 throws UnsupportedOperationException, 127 NullPointerException, 128 IllegalStateException; 129 130 /** 131 * A convenience function to append a new member to the end of this 132 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 133 * collection 134 * 135 * @param aMember 136 * a new relationship 137 * @return this Accumulator (facilitates operations chaining) 138 * 139 * @throws UnsupportedOperationException 140 * this Accumulator's relationship collection could not be changed 141 * @throws NullPointerException 142 * a {@code null} value was provided where none was expected 143 * @throws IllegalStateException 144 * this Accumulator's relationship collection could not be changed 145 * at this time 146 */ 147 public ACCUMULATOR push( final BigInteger aMember ) 148 throws UnsupportedOperationException, 149 NullPointerException, 150 IllegalStateException; 151 152 /** 153 * A convenience function to append a new member to the end of this 154 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 155 * collection 156 * 157 * @param aMember 158 * a new relationship 159 * @return this Accumulator (facilitates operations chaining) 160 * 161 * @throws UnsupportedOperationException 162 * this Accumulator's relationship collection could not be changed 163 * @throws NullPointerException 164 * a {@code null} value was provided where none was expected 165 * @throws IllegalStateException 166 * this Accumulator's relationship collection could not be changed 167 * at this time 168 */ 169 public ACCUMULATOR push( final boolean aMember ) 170 throws UnsupportedOperationException, 171 NullPointerException, 172 IllegalStateException; 173 174 /** 175 * A convenience function to append a new member to the end of this 176 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 177 * collection 178 * 179 * @param aMember 180 * a new relationship 181 * @return this Accumulator (facilitates operations chaining) 182 * 183 * @throws UnsupportedOperationException 184 * this Accumulator's relationship collection could not be changed 185 * @throws NullPointerException 186 * a {@code null} value was provided where none was expected 187 * @throws IllegalStateException 188 * this Accumulator's relationship collection could not be changed 189 * at this time 190 */ 191 public ACCUMULATOR push( final byte aMember ) 192 throws UnsupportedOperationException, 193 NullPointerException, 194 IllegalStateException; 195 196 /** 197 * A convenience function to append a new member to the end of this 198 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 199 * collection 200 * 201 * @param aMember 202 * a new relationship 203 * @return this Accumulator (facilitates operations chaining) 204 * 205 * @throws UnsupportedOperationException 206 * this Accumulator's relationship collection could not be changed 207 * @throws NullPointerException 208 * a {@code null} value was provided where none was expected 209 * @throws IllegalStateException 210 * this Accumulator's relationship collection could not be changed 211 * at this time 212 */ 213 public ACCUMULATOR push( final char aMember ) 214 throws UnsupportedOperationException, 215 NullPointerException, 216 IllegalStateException; 217 218 /** 219 * A convenience function to append a new member to the end of this 220 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 221 * collection 222 * 223 * @param aMember 224 * a new relationship 225 * @return this Accumulator (facilitates operations chaining) 226 * 227 * @throws UnsupportedOperationException 228 * this Accumulator's relationship collection could not be changed 229 * @throws NullPointerException 230 * a {@code null} value was provided where none was expected 231 * @throws IllegalStateException 232 * this Accumulator's relationship collection could not be changed 233 * at this time 234 */ 235 public ACCUMULATOR push( final double aMember ) 236 throws UnsupportedOperationException, 237 NullPointerException, 238 IllegalStateException; 239 240 /** 241 * A convenience function to append a new member to the end of this 242 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 243 * collection 244 * 245 * @param aMember 246 * a new relationship 247 * @return this Accumulator (facilitates operations chaining) 248 * 249 * @throws UnsupportedOperationException 250 * this Accumulator's relationship collection could not be changed 251 * @throws NullPointerException 252 * a {@code null} value was provided where none was expected 253 * @throws IllegalStateException 254 * this Accumulator's relationship collection could not be changed 255 * at this time 256 */ 257 public ACCUMULATOR push( final float aMember ) 258 throws UnsupportedOperationException, 259 NullPointerException, 260 IllegalStateException; 261 262 /** 263 * A convenience function to append a new member to the end of this 264 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 265 * collection 266 * 267 * @param aMember 268 * a new relationship 269 * @return this Accumulator (facilitates operations chaining) 270 * 271 * @throws UnsupportedOperationException 272 * this Accumulator's relationship collection could not be changed 273 * @throws NullPointerException 274 * a {@code null} value was provided where none was expected 275 * @throws IllegalStateException 276 * this Accumulator's relationship collection could not be changed 277 * at this time 278 */ 279 public ACCUMULATOR push( final int aMember ) 280 throws UnsupportedOperationException, 281 NullPointerException, 282 IllegalStateException; 283 284 /** 285 * A convenience function to append a new member to the end of this 286 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 287 * collection 288 * 289 * @param aMember 290 * a new relationship 291 * @return this Accumulator (facilitates operations chaining) 292 * 293 * @throws UnsupportedOperationException 294 * this Accumulator's relationship collection could not be changed 295 * @throws NullPointerException 296 * a {@code null} value was provided where none was expected 297 * @throws IllegalStateException 298 * this Accumulator's relationship collection could not be changed 299 * at this time 300 */ 301 public ACCUMULATOR push( final long aMember ) 302 throws UnsupportedOperationException, 303 NullPointerException, 304 IllegalStateException; 305 306 /** 307 * A convenience function to append a new member to the end of this 308 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 309 * collection 310 * 311 * @param aMember 312 * a new relationship 313 * @return this Accumulator (facilitates operations chaining) 314 * 315 * @throws UnsupportedOperationException 316 * this Accumulator's relationship collection could not be changed 317 * @throws NullPointerException 318 * a {@code null} value was provided where none was expected 319 * @throws IllegalStateException 320 * this Accumulator's relationship collection could not be changed 321 * at this time 322 */ 323 public ACCUMULATOR push( final short aMember ) 324 throws UnsupportedOperationException, 325 NullPointerException, 326 IllegalStateException; 327 328 /** 329 * A convenience function to append a new keyed (named) member to the end of 330 * this Accumulator's {@link SealedSealedAccumulator#members() relationship} 331 * collection 332 * 333 * @param aKey 334 * a new key (name) 335 * @param aMember 336 * a new relationship 337 * @return this Accumulator (facilitates operations chaining) 338 * 339 * @throws UnsupportedOperationException 340 * this Accumulator's relationship collection could not changed 341 * @throws NullPointerException 342 * a {@code null} value was provided where none was expected 343 * @throws IllegalStateException 344 * this Accumulator's relationship collection could not be changed 345 * at this time 346 */ 347 public ACCUMULATOR push( final String aKey, final Accumulator<?> aMember ) 348 throws UnsupportedOperationException, 349 NullPointerException, 350 IllegalStateException; 351 352 /** 353 * A convenience function to append a new member to the end of this 354 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 355 * collection 356 * 357 * @param aMember 358 * a new relationship 359 * @return this Accumulator (facilitates operations chaining) 360 * 361 * @throws UnsupportedOperationException 362 * this Accumulator's relationship collection could not be changed 363 * @throws NullPointerException 364 * a {@code null} value was provided where none was expected 365 * @throws IllegalStateException 366 * this Accumulator's relationship collection could not be changed 367 * at this time 368 */ 369 public ACCUMULATOR pushPrimitive( final Primitive<?> aMember ) 370 throws UnsupportedOperationException, 371 NullPointerException, 372 IllegalStateException; 373 374 /** 375 * A convenience function to append a new member to the end of this 376 * Accumulator's {@link SealedSealedAccumulator#members() relationship} 377 * collection 378 * 379 * @param aMember 380 * a new relationship 381 * @return this Accumulator (facilitates operations chaining) 382 * 383 * @throws UnsupportedOperationException 384 * this Accumulator's relationship collection could not be changed 385 * @throws NullPointerException 386 * a {@code null} value was provided where none was expected 387 * @throws IllegalStateException 388 * this Accumulator's relationship collection could not be changed 389 * at this time 390 */ 391 public ACCUMULATOR pushText( final CharSequence aMember ) 392 throws UnsupportedOperationException, 393 NullPointerException, 394 IllegalStateException; 395 396 /** 397 * Attempt to change this Accumulator's relationships to the relationships 398 * of the specified Accumulator (shallow copy) 399 * 400 * @param anAccumulator 401 * the Accumulator to query 402 * @return this Accumulator (facilitates operations chaining) 403 * 404 * @throws UnsupportedOperationException 405 * this Accumulator's relationships could not be changed 406 * @throws NullPointerException 407 * a {@code null} value was provided where none was expected 408 * @throws IllegalStateException 409 * this Accumulator's relationships could not be changed at this 410 * time 411 * @throws IllegalArgumentException 412 * an aspect of the specified relationships were incompatible with 413 * this Accumulator's specification 414 * 415 * @see SealedAccumulator#getTarget() 416 */ 417 public ACCUMULATOR replaceRelationshipsUsing( 418 final Accumulator<?> anAccumulator ) 419 throws UnsupportedOperationException, 420 NullPointerException, 421 IllegalStateException, 422 IllegalArgumentException; 423 424 /** 425 * Attempt to {@link #shareTarget(Primitive) share} the target of the 426 * specified Accumulator with this Accumulator, and also 427 * {@link #replaceRelationshipsUsing(Accumulator) mirror} this Accumulator's 428 * relationships to the relationship map of the specified Accumulator. 429 * 430 * @param anAccumulator 431 * the Accumulator to query 432 * @return this Accumulator (facilitates operations chaining) 433 * 434 * @throws UnsupportedOperationException 435 * either this Accumulator's target or relationships could not be 436 * changed 437 * @throws NullPointerException 438 * a {@code null} value was provided where none was expected 439 * @throws IllegalStateException 440 * either this Accumulator's target or relationships could not be 441 * changed at this time 442 * @throws IllegalArgumentException 443 * an aspect of the specified target or relationships were 444 * incompatible with this Accumulator's specification 445 * 446 * @see #shareTarget(Primitive) 447 * @see #replaceRelationshipsUsing(Accumulator) 448 */ 449 public ACCUMULATOR setAccumulator( final Accumulator<?> anAccumulator ) 450 throws UnsupportedOperationException, 451 NullPointerException, 452 IllegalStateException, 453 IllegalArgumentException; 454 455 /** 456 * Attempt to share the specified {@link Primitive} target with this 457 * Accumulator, or, if this Accumulator's target could not be 458 * {@link SealedAccumulator#isTargetReplaceable() replaced}, attempt to 459 * change the current target's value 460 * 461 * @param aTarget 462 * a new target 463 * @return this Accumulator (facilitates operations chaining) 464 * 465 * @throws UnsupportedOperationException 466 * this Accumulator's target, or the target's value, could not be 467 * changed 468 * @throws NullPointerException 469 * a {@code null} value was provided where none was expected 470 * @throws IllegalStateException 471 * this Accumulator's target, or the target's value, could not be 472 * changed at this time 473 * @throws IllegalArgumentException 474 * an aspect of the new target was incompatible with this 475 * Accumulator's specification, or this Accumulator's target's 476 * specification 477 * 478 * @see SealedAccumulator#getTarget() 479 */ 480 public ACCUMULATOR shareTarget( final Primitive<?> aTarget ) 481 throws UnsupportedOperationException, 482 NullPointerException, 483 IllegalStateException, 484 IllegalArgumentException; 485 486 /** 487 * Attempt to share the specified Accumulator's {@link Primitive} target 488 * with this Accumulator, or, if this Accumulator's target could not be 489 * {@link SealedAccumulator#isTargetReplaceable() replaced}, attempt to 490 * change the current target's value 491 * 492 * @param anAccumulator 493 * the Accumulator to query 494 * @return this Accumulator (facilitates operations chaining) 495 * 496 * @throws UnsupportedOperationException 497 * this Accumulator's target, or the target's value, could not be 498 * changed 499 * @throws NullPointerException 500 * a {@code null} value was provided where none was expected 501 * @throws IllegalStateException 502 * this Accumulator's target, or the target's value, could not be 503 * changed at this time 504 * @throws IllegalArgumentException 505 * an aspect of the new target was incompatible with this 506 * Accumulator's specification, or this Accumulator's target's 507 * specification 508 * 509 * @see SealedAccumulator#getTarget() 510 */ 511 public ACCUMULATOR shareTargetWith( final Accumulator<?> anAccumulator ) 512 throws UnsupportedOperationException, 513 NullPointerException, 514 IllegalStateException, 515 IllegalArgumentException; 516}