001    /*
002    Copyright (c) 1996-2009, Damon Hart-Davis
003    All rights reserved.
004    
005    Redistribution and use in source and binary forms, with or without
006    modification, are permitted provided that the following conditions are
007    met:
008    
009      * Redistributions of source code must retain the above copyright
010        notice, this list of conditions and the following disclaimer.
011    
012      * Redistributions in binary form must reproduce the above copyright
013        notice, this list of conditions and the following disclaimer in the
014        documentation and/or other materials provided with the
015        distribution.
016    
017    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
018    IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
019    TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
020    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
021    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
022    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
023    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
024    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
025    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
026    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
027    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
028    */
029    package org.hd.d.pg2k.svrCore.vars;
030    
031    import java.io.IOException;
032    
033    /**
034     * Created by IntelliJ IDEA.
035     * User: Damon
036     * Date: 19-Aug-2004
037     * Time: 14:11:03
038     */
039    
040    /**Simple interface implemented by several stages in the Web distributed-variable-handling pipeline.
041     * The pipeline stages that implement this may well implement other interfaces
042     * in parallel to provide richer and more efficient cacheing, etc.
043     */
044    public interface SimpleVariablePipelineIF extends BasicVarMgrInterface
045        {
046        /**Synchronise variables with upstream values.
047         * Pushes updated values upstream to the source,
048         * calls sync on the source if called with the "force" argument true,
049         * and then retrieves changed values from upstream.
050         * <p>
051         * When called with force==true, this acts like a full "memory barrier",
052         * flushing all write-cached items downstream immediately and afterwards
053         * getting the value of all upstream values with getVariables(-1),
054         * but may be expensive in terms of CPU or bandwidth, so use sparingly.
055         * <p>
056         * When called with force==false, this incrementally flushes outstanding
057         * writes and will then fetch all, or only new, values from upstream,
058         * so is potentially much less resource-intensive.
059         * In particular, this does not propagate the sync() upstream.
060         * <p>
061         * In any case, it is rarely the right thing for a casual user
062         * to call this as it may be very expensive.
063         *
064         * @param force  if true, this will force a full write flush,
065         *     a full sync upstream,
066         *     then full read with getVariables(-1),
067         *     to get the effect of a full "barrier";
068         *     otherwise, in general, a more incremental and non-propagating
069         *     mode is used which still does a write flush but may chose
070         *     to do a partial read of "new" upstream values
071         *
072         * @throws java.io.IOException if one is received from upstream
073         */
074        public void syncVariables(final boolean force)
075            throws IOException;
076        }