package votorola.s.gwt.scene.feed.ss; // Copyright 2011, Michael Allan.  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE.

import java.io.*;
import java.sql.*;
import java.util.*;
import votorola.a.*;
import votorola.a.trust.*;
import votorola.g.lang.*;


/** A configurer of bites on the server side.  After the feed server has configured a bite
  * according to its own requirements, it may process the bite through one or more biters
  * for additional configuration.  The exact biters it uses for this purpose will depend
  * on the current composition of the client, in particular on the type of scene it is
  * displaying.  Different types of scene have different requirements in the way of extended
  * bite properties.  Decorating the bites with those properties on the server side (using
  * a biter) is intended as an optimization for speed.  It eliminates the need for client
  * maps to make separate calls to the server for each bite displayed.  So users will be
  * able to juxtapose any feed type with any scene type and the server won't be brought to
  * its knees keeping all the combinations fed with data.  Biters (working on jigs) ought
  * to be very fast.  They decorate the bite stream on the fly (in mid-transmission) with
  * whatever additional data is required for the user's chosen scene, and they do so without
  * a lot of garbage overhead.
  */
public interface Biter
{


   // - B i t e r ------------------------------------------------------------------------


     /** Configures a bite.  Uses the various add/set methods of the bite jig to ensure
       * that all necessary properties of the bite are set.
       */
     public void configure( BiteJig bite );



   // ====================================================================================


    /** Biter utilities.
      */
    public @ThreadSafe static final class U
    {

        private U() {}


        /** Assembles an array of biters suitable for handling a particular request to a
          * bite feed.  The biters ought to be invoked in the same order as stored in the
          * array.  Do not hold them for any great length of time; they contain perishable
          * data, such as network traces or counts.
          */
          @Warning("thread restricted object")
        public static final Biter[] assembleBiters( final VoteServer.Run run )
          throws IOException, SQLException
        {
            final NetworkTrace traceOrNull = run.trustserver().traceToReportT();
            // We'll eventually do something more intelligent here, depending on which scene
            // is currently shown in the theatre client.  But for now, it's OK to assemble
            // all possible biters:
            return new Biter[]
            {
                new votorola.s.gwt.scene.geo.GeomapBiterSS( run, traceOrNull ),
                new votorola.s.gwt.scene.vote.VotespaceBiterSS( run )
            };
        }


    }


}