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}