package votorola.s.gwt.scene.feed; // Copyright 2010-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 com.google.gwt.core.client.*;
import com.google.web.bindery.event.shared.*;
import com.google.gwt.view.client.*;
import com.google.gwt.user.client.ui.*;
import java.util.List;
import votorola.a.web.gwt.*;
import votorola.s.gwt.scene.*;
import votorola.s.gwt.scene.diff.*;
import votorola.s.gwt.scene.dum.*;
import votorola.g.hold.*;
import votorola.g.web.gwt.*;
import votorola.g.web.gwt.event.*;

/** A temporal sequence of real-world events (bites) unfolding in semi-real time.
  */
public abstract class Feed extends ListDataProvider<BiteJS>
{


    /** Constructs a Feed.
      */
    public Feed( List<BiteJS> listToWrap ) { super( listToWrap ); }



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


    /** Short names designating particular feed types, suitable for use in a ({@linkplain
      * Scenes#cCompositionSwitch() composition switch}).  Each name begins with a single
      * ASCII uppercase letter which may be followed by zero or more ASCII lowercase
      * letters and digits.
      *
      *     @see votorola.s.gwt.scene.Scene.SwitchMnemonic
      */
    public static enum SwitchMnemonic
    {


        /** Designating a {@linkplain DiffFeed DiffFeed}.
          */
        D
        {
            public Hold emplace()
            {
                final Spool spool = new Spool1();
                final DiffFeed feed = new DiffFeed();
                spool.add( feed );

                final FeedVCellList feedV = new FeedVCellList( new DiffBiteVCell() );
                feed.addDataDisplay( feedV );
                addView( feedV, spool );
                return new SpoolHold( spool );
            }
        },



        /** Designating a {@linkplain DummyFeed DummyFeed}.
          */
        Dum
        {
            public Hold emplace()
            {
                final Spool spool = new Spool1();
                final DummyFeed feed = new DummyFeed();
                spool.add( feed );

                final FeedVCellList feedV = new FeedVCellList( new DummyBiteVCell() );
                feed.addDataDisplay( feedV );
                addView( feedV, spool );
                return new SpoolHold( spool );
            }
        };



       // --------------------------------------------------------------------------------


        private static void addView( final Widget feedV, final Spool spool )
        {
            ScenesV.i().setFeed( feedV );
            spool.add( new Hold() { public void release() { feedV.removeFromParent(); }});
        }



        /** Constructs and emplaces the designated feed model, views and controllers.
          *
          *     @return a hold the release of which undoes the emplacement.
          */
        public abstract Hold emplace();


    }



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


    /** A filter-based feed scoper that works from an unfiltered reference list.
      */
    protected final class UnScoper implements ScopeChangeHandler, PropertyChangeHandler,
      Scheduler.RepeatingCommand
    {


        /** Constructs an UnScoper.
          *
          *     @see #listMaxSize()
          *     @see #unList()
          *     @param spool for release of internal holds.  When unwound, this instance will
          *         release its internal holds and become disabled.
          */
        public UnScoper( int _listMaxSize, List<BiteJS> _unList, final Spool spool )
        {
            listMaxSize = _listMaxSize;
            unList = _unList;
            assert listMaxSize <= FeedVCellList.PAGE_SIZE: "listMaxSize cannot exceed " + FeedVCellList.PAGE_SIZE;

            spool.add( new Hold()
            {
                final HandlerRegistration hR = ScopeChangeEvent.addHandler( UnScoper.this );
                public void release() { hR.removeHandler(); }
            });
            spool.add( new Hold()
            {
                final HandlerRegistration hR = GWTX.i().bus().addHandlerToSource(
                  PropertyChange.TYPE, /*source*/Scenes.i(), UnScoper.this );
                public void release() { hR.removeHandler(); }
            });
        }



        private void executeLater() { spreadScheduler.schedule(); }
          // Spread the load for a snappier response during scene or scope changes.  This
          // also has the effect of allowing some extra time for scoping to initialize.
          // Geoscoping in particular is slow to learn the extent of a newly constructed
          // geomap.



        private final CoalescingSchedulerR spreadScheduler = new CoalescingSchedulerR(
          new CoalescingSchedulerR.FixedPeriod(500/*ms*/), UnScoper.this );



       // --------------------------------------------------------------------------------


        /** The length limit for the feed list.  The scoper will not allow it to grow
          * longer regardless of the degree of filtering.  This limit has no bearing on
          * the capacity of the {@linkplain #unList() unfiltered reference list}, which
          * ought normally to be much larger.
          *
          *     @see Feed#getList()
          */
        public int listMaxSize() { return listMaxSize; };


            private final int listMaxSize;



        /** The unfiltered reference list of bites from which the filtered list is derived
          * during scoping.
          */
        public final List<BiteJS> unList() { return unList; }


            private final List<BiteJS> unList;



       // - P r o p e r t y - C h a n g e - H a n d l e r --------------------------------


        public void onPropertyChange( final PropertyChange e )
        {
            if( !"scene".equals( e.propertyName() )) return;

            if( Scenes.i().scene() == Scene0.i() ) return; // in transition, ignore it

            executeLater();
        }



       // - S c h e d u l e r . R e p e a t i n g - C o m m a n d ------------------------


        public boolean execute()
        {
            final Scene scene = Scenes.i().scene();
            final List<BiteJS> list = getList();
            list.clear();
            for( final BiteJS bite: unList )
            {
                if( !scene.inScope( bite )) continue;

                list.add( bite );
                if( list.size() >= listMaxSize ) break;
            }

            return /*to repeat*/false;
        }



       // - S c o p e - C h a n g e - H a n d l e r --------------------------------------


        public void onScopeChange( final ScopeChangeEvent e ) { executeLater(); }


    }



}