petraframe-svn Mailing List for PetraGameFrame

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Revision: 15
          http://petraframe.svn.sourceforge.net/petraframe/?rev=15&view=rev
Author:   janet-h
Date:     2011-07-11 17:38:33 +0000 (Mon, 11 Jul 2011)

Log Message:
-----------
roundup on preloading manager
added preloading event listening to resource manager

Modified Paths:
--------------
    PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManager.java
    PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManagerImpl.java

Added Paths:
-----------
    PETRA1/trunk/src/net/petraframe/event/
    PETRA1/trunk/src/net/petraframe/event/PGFPreloadEvent.java
    PETRA1/trunk/src/net/petraframe/event/PGFPreloadEventListener.java

Added: PETRA1/trunk/src/net/petraframe/event/PGFPreloadEvent.java
===================================================================

--- PETRA1/trunk/src/net/petraframe/event/PGFPreloadEvent.java	                        (rev 0)
+++ PETRA1/trunk/src/net/petraframe/event/PGFPreloadEvent.java	2011-07-11 17:38:33 UTC (rev 15)
@@ -0,0 +1,93 @@
+package net.petraframe.event;
+
+import java.util.EventObject;
+
+import net.petraframe.res.data.PGFDataResource;
+
+public class PGFPreloadEvent extends EventObject {
+   private static final long serialVersionUID = 9205167344938402777L;
+
+   public static enum PreloadEventType {FAILED, STARTED, PERFORMED};
+   
+   private PGFDataResource resource;
+   private long timestamp;
+   private int duration;
+   private PreloadEventType type;
+   private Throwable error;
+   
+   /**
+    * Create a preload event.
+    * 
+    * @param source Object (may be <b>null</b>)
+    * @param type PreloadEventType type of this event
+    * @param res PGFDataResource  the data resource associated with this event
+    * @param time long epoch milliseconds when this event occurred (may be 0)
+    * @param duration int milliseconds of loading duration (may be 0)
+    * @throws NullPointerException if type or res are null
+    */
+   public PGFPreloadEvent(
+         Object source, 
+         PreloadEventType type,
+         PGFDataResource res, 
+         long time,
+         int duration ) {
+      
+      super(source);
+      if (type == null | res == null) {
+         throw new NullPointerException();
+      }
+      this.type = type;
+      this.resource = res;
+      this.timestamp = time == 0 ? System.currentTimeMillis() : time;
+      this.duration = duration;
+   }
+
+   /** The data resource associated with this event.
+    * 
+    * @return <code>PGFDataResource</code> data resource
+    */
+   public PGFDataResource getResource() {
+      return resource;
+   }
+
+   /** Time when this event occurred.
+    * 
+    * @return long epoch milliseconds
+    */
+   public long getTimestamp() {
+      return timestamp;
+   }
+
+   /** Duration of data loading. May be 0 to indicate unavailability.
+    *  
+    * @return int milliseconds
+    */
+   public int getDuration() {
+      return duration;
+   }
+
+   /** Event type.
+    * 
+    * @return PGFPreloadEvent.PreloadEventType
+    */
+   public PreloadEventType getType() {
+      return type;
+   }
+
+   /** Error message in case of a failure event.
+    * 
+    * @return <code>Throwable</code> or <b>null</b>
+    */
+   public Throwable getError() {
+      return error;
+   }
+
+   /** Sets the error message for this event.
+    * 
+    * @param error <code>Throwable</code> or <b>null</b>
+    */
+   public void setError (Throwable error) {
+      this.error = error;
+   }
+
+}


Property changes on: PETRA1/trunk/src/net/petraframe/event/PGFPreloadEvent.java
___________________________________________________________________
Added: svn:mime-type
   + text/x-java
Added: svn:eol-style
   + native

Added: PETRA1/trunk/src/net/petraframe/event/PGFPreloadEventListener.java
===================================================================
--- PETRA1/trunk/src/net/petraframe/event/PGFPreloadEventListener.java	                        (rev 0)
+++ PETRA1/trunk/src/net/petraframe/event/PGFPreloadEventListener.java	2011-07-11 17:38:33 UTC (rev 15)
@@ -0,0 +1,14 @@
+package net.petraframe.event;
+
+public interface PGFPreloadEventListener {
+   
+   /**
+    * Called for any of the preloading event types.
+    * This method is expected to terminate quickly. 
+    * Implementation should analyse the event type!
+    * 
+    * @param evt <code>PGFPreloadEvent</code>
+    */
+   public void resourcePreloadingEventPerformed (PGFPreloadEvent evt);
+
+}


Property changes on: PETRA1/trunk/src/net/petraframe/event/PGFPreloadEventListener.java
___________________________________________________________________
Added: svn:mime-type
   + text/x-java
Added: svn:eol-style
   + native

Modified: PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManager.java
===================================================================
--- PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManager.java	2011-07-04 19:32:34 UTC (rev 14)
+++ PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManager.java	2011-07-11 17:38:33 UTC (rev 15)
@@ -8,6 +8,17 @@
 import javax.swing.ImageIcon;
 import javax.swing.event.ChangeListener;
 
+import net.petraframe.event.PGFPreloadEventListener;
+
+/**
+ * The Resource Manager makes available read-only external data resources
+ * of the application by call of their names, which are free to design.
+ * Furthermore resources can be selected to be kept in a cache for quick
+ * access and preloaded automatically when the manager starts.
+ * 
+ * @author janet-h
+ *
+ */
 public interface PGFResourceManager {
 
 /**
@@ -70,14 +81,14 @@
  * changes (valid/invalid), or when the set of mappings has been
  * modified.
  * 
- * @param listener <code>ChangeListener</code>
+ * @param listener <code>javax.swing.event.ChangeListener</code>
  */
 public void addChangeListener (ChangeListener listener);
 
 /**
  * Removes a change listener from this manager.
  * 
- * @param listener
+ * @param listener <code>javax.swing.event.ChangeListener</code>
  */
 public void removeChangeListener (ChangeListener listener);
 
@@ -149,4 +160,21 @@
  */
 public ImageIcon getImageIcon (String name) throws IOException;
 
+/**
+ * Adds a preloading listener to this manager. A preloading event
+ * is issued for each resource a) when preloading started, b) when
+ * preloading finished successfully (performed), and c) when
+ * preloading failed.  
+ * 
+ * @param listener {@link PGFPreloadEventListener}
+ */
+public void addPreloadEventListener(PGFPreloadEventListener listener);
+
+/**
+ * Removes a preloading listener to this manager.
+ * 
+ * @param listener {@link PGFPreloadEventListener}
+ */
+public void removePreloadEventListener(PGFPreloadEventListener listener);
+
 }

Modified: PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManagerImpl.java
===================================================================
--- PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManagerImpl.java	2011-07-04 19:32:34 UTC (rev 14)
+++ PETRA1/trunk/src/net/petraframe/res/data/PGFResourceManagerImpl.java	2011-07-11 17:38:33 UTC (rev 15)
@@ -19,6 +19,8 @@
 import javax.swing.event.ChangeEvent;
 import javax.swing.event.ChangeListener;
 
+import net.petraframe.event.PGFPreloadEvent;
+import net.petraframe.event.PGFPreloadEventListener;
 import net.petraframe.exception.PGFPreloadFailureException;
 
 public class PGFResourceManagerImpl implements PGFResourceManager {
@@ -29,6 +31,8 @@
    
    public static int maxCacheEntries = 0;
 
+   public static int initialCacheCapacity = 500;
+
    public static long maxCacheDataSize = 10000000; // 10 MB
    
    public static int maxJobsParallel = 10;
@@ -42,13 +46,17 @@
    /** The map referring to resource directory objects. Realises all available resource directory paths. */ 
    private TreeMap<String, PGFResourceDirectory> directoryMap = new TreeMap<String, PGFResourceDirectory>();
    
+   /** The map that realises the preloaded resources data cache. Entries in this cache
+    * are not removed except by <code>invalidateResources()</code>. */
    private Hashtable<String, byte[]> preloadCache = new Hashtable<String, byte[]>();
    
+   /** Structure realising the "live" data cache. */
    private DataCache dataCache = new DataCache(maxCacheEntries, maxCacheDataSize); 
 
    private PreloadingManager preloadingManager;
    private List<URL> mappingSources;
    private ArrayList<ChangeListener> changeListeners;
+   private ArrayList<PGFPreloadEventListener> preloadEventListeners;
    
    private boolean isValid = false;
    
@@ -103,7 +111,9 @@
 
    /**
     * Searches for a cache data entry for the given resource
-    * and returns the cached data when found.
+    * and returns the cached data when found. (The search goes
+    * into preload or "live" data cache, depending on what
+    * is logically set in the resource.)
     * 
     * @param resource <code>PGFDataResource</code>
     * @return <code>byte[]</code> or <b>null</b> if entry is not found
@@ -158,6 +168,7 @@
                throw new PGFPreloadFailureException();
             }
             // access resource data directly and cache the results if opted
+            // otherwise the input stream is returned as is
             input = resource.getResourceURL().openStream();
             if (resource.isCachable()) {
                // if resource is cachable, create data block and add to cache
@@ -166,7 +177,7 @@
             }
          } 
 
-         // serialise a cached data block
+         // serialise into a stream if a data block has been cached
          if (block != null) {
             input = new ByteArrayInputStream(block);
          }
@@ -261,13 +272,13 @@
    }
 
    /**
-    * Analyses a mapping definition file under the given url
+    * Analyses a mapping definition file under the given URL
     * and fills mappings into both single and complex resource maps.
     * 
     * @param url URL of the mapping file
     * @throws Exception
     */
-   private void analyseMappings (URL url) throws Exception {
+   protected void analyseMappings (URL url) throws Exception {
       // TODO Analyse an external mapping definition file
       
       
@@ -301,8 +312,12 @@
       }
    }
 
+   /**
+    * Distributes a <code>javax.swing.event.ChangeEvent</code> to all change
+    * listeners of this manager. (Buffered list execution)
+    */
    @SuppressWarnings("unchecked")
-   private synchronized void fireChangeEvent () {
+   protected synchronized void fireChangeEvent () {
       List<ChangeListener> copy;
 
       if (changeListeners != null) {
@@ -401,8 +416,11 @@
     * @param v boolean <b>true</b> == cachable, <b>false</b> == not cachable
     * @return boolean <b>true</b> if and only if the resource is registered for caching
     */
-   protected boolean setCachableResource (PGFDataResourceImpl resource, boolean v) {
-      return false;
+   protected boolean setCachableResource (PGFDataResource resource, boolean v) {
+      if (!v) {
+         dataCache.removeEntry(resource.getName());
+      }
+      return v;
    }
    
    /**
@@ -414,7 +432,7 @@
     * @return boolean <b>true</b> if and only if the resource is registered for 
     *         preloading
     */
-   protected boolean setPreloadingResource (PGFDataResourceImpl resource, boolean v) {
+   protected boolean setPreloadingResource (PGFDataResource resource, boolean v) {
       
       String key = resource.getName();
       boolean hasData = preloadCache.containsKey(key);
@@ -438,10 +456,21 @@
       return preload;
    }
 
+   /**
+    * Puts a resource's block of data into the "live" cache of this manager.
+    * 
+    * @param resource <code>PGFDataResource</code> associated resource
+    * @param data byte[] data block to go into the cache
+    */
    private void addDataCacheEntry(PGFDataResource resource, byte[] data) {
       dataCache.addEntry(resource.getName(), data);
    }
 
+   /**
+    * Adds a preloading job for the given data resource.
+    * 
+    * @param resource
+    */
    private void addPreloadingJob(PGFDataResource resource) {
       if (resource == null) {
          throw new NullPointerException();
@@ -452,35 +481,156 @@
       preloadingManager.createPreloadingJob(resource);
    }
    
+   /**
+    * Distributes a <code>PGFPreloadEvent</code> to all preload listeners of 
+    * this manager. (Buffered list execution)
+    */
+   @SuppressWarnings("unchecked")
+   private void runPreloadEvent (PGFPreloadEvent evt) {
+      List<PGFPreloadEventListener> copy;
+
+      if (preloadEventListeners != null) {
+         synchronized (preloadEventListeners) {
+            copy = (List<PGFPreloadEventListener>)preloadEventListeners.clone();
+         }
+         for (PGFPreloadEventListener l : copy) {
+            l.resourcePreloadingEventPerformed(evt);
+         }
+      }
+   }
+
+   @Override
+   public synchronized void addPreloadEventListener(PGFPreloadEventListener listener) {
+      if (listener != null) {
+         // late creation of list
+         if (preloadEventListeners == null) {
+            preloadEventListeners = new ArrayList<PGFPreloadEventListener>();
+         }
+         // synchronized list modification
+         synchronized(preloadEventListeners) {
+            if (listener != null && !preloadEventListeners.contains(listener)) {
+               preloadEventListeners.add(listener);
+            }
+         }
+      }
+   }
+
+   @Override
+   public void removePreloadEventListener(PGFPreloadEventListener listener) {
+      if (preloadEventListeners != null & listener != null) {
+         // synchronized list modification
+         synchronized(preloadEventListeners) {
+            if (listener != null) {
+               preloadEventListeners.remove(listener);
+            }
+         }
+      }
+   }
+
+   /**
+    * Fires a preloading event of type <code>PGFPreloadEvent.PreloadEventType.PERFORMED</code>
+    * to all preload listeners of this manager.
+    *   
+    * @param resource PGFDataResource data resource
+    * @param time long epoch milliseconds when this event occurred (may be 0 for auto-completion)
+    * @param duration int milliseconds of loading duration (may be 0)
+    */
+   protected synchronized void fireResourcePreloadedEvent(PGFDataResource resource, long time, int duration) {
+      PGFPreloadEvent event = new PGFPreloadEvent(this, PGFPreloadEvent.PreloadEventType.PERFORMED, 
+            resource, time, duration);
+      runPreloadEvent(event);
+   }
+
+   /**
+    * Fires a preloading event of type <code>PGFPreloadEvent.PreloadEventType.STARTED</code>
+    * to all preload listeners of this manager.
+    *   
+    * @param resource PGFDataResource data resource
+    * @param time long epoch milliseconds when this event occurred (may be 0 for auto-completion)
+    */
+   protected synchronized void firePreloadStartedEvent(PGFDataResource resource, long time) {
+      PGFPreloadEvent event = new PGFPreloadEvent(this, PGFPreloadEvent.PreloadEventType.STARTED, 
+            resource, time, 0);
+      runPreloadEvent(event);
+   }
+
+   /**
+    * Fires a preloading event of type <code>PGFPreloadEvent.PreloadEventType.FAILED</code>
+    * to all preload listeners of this manager.
+    *   
+    * @param resource PGFDataResource data resource
+    * @param time long epoch milliseconds when this event occurred (may be 0 for auto-completion)
+    * @param error Throwable (may be <b>null</b>)
+    */
+   protected synchronized void firePreloadingFailureEvent(PGFDataResource resource,
+             long time, Throwable error) {
+      PGFPreloadEvent event = new PGFPreloadEvent(this, PGFPreloadEvent.PreloadEventType.FAILED, 
+            resource, time, 0);
+      event.setError(error);
+      runPreloadEvent(event);
+   }
+   
 // + + + + + + + + CLASSES + + + + + + + + + + +     
 
+/** The Preloading Manager organises fetching of external data for resources
+ * which have been marked as "preload=true" in the resource definition files (XML).
+ * Once the data has been fetched, an entry with the block is put into the 
+ * <code>preloadCache</code> of the resource manager.
+ * The manager has a single public method, namely "createPreloadingJob" with a resource
+ * as argument. Any number of preloading jobs can be filed instantly and will get
+ * processed by the manager in an orderly way. Up to x URL loading jobs are
+ * performed simultaneously, where x is defined by global value <i>maxJobsParallel</i>
+ * of PGFResourceManagerImpl. 
+ * <p>A controller daemon thread owned by this manager is created on demand and 
+ * kept alive only as long as needed to organise the list of waiting jobs. Each 
+ * loading job for a resource runs in a separate thread.
+ * <p>Also see: {@link PreloadingJob}
+ */
 private class PreloadingManager {
    private List<PGFDataResource> waiting = new LinkedList<PGFDataResource>();
    private List<PreloadingJob> running = new LinkedList<PreloadingJob>();
+   private boolean modified;
    
    private Thread controller;
    
+   private void setJobFinished () {
+      modified = true;
+   }
+   
+   /**
+    * Unconditionally creates a preloading job for the given data resource.
+    *  
+    * @param res <code>PGFDataResource</code> 
+    */
    public synchronized void createPreloadingJob (PGFDataResource res) {
-      // add resource to the waiting queue
+      if (res == null) {
+         throw new NullPointerException();
+      }
+      // add given resource to the waiting queue
       synchronized (waiting) {
          waiting.add(res);
       }
-      // create the controller of jobs
+      // create the controller of jobs (service daemon) if not alive
       if (controller == null || !controller.isAlive()) {
          controller = new Thread("PGF preloading controller") {
 
             @Override
             public void run() {
+               // starting controller: make sure we clean the job list first
                boolean terminate = false;
-               while (!terminate) {
-                  // clean the job list
+               modified = true;
+               
+               // service loop until terminated by waiting.size==0
+               while (!terminate & modified) {
+                  // step 1: clean the job list
+                  modified = false;
                   for (Iterator<PreloadingJob> it = running.iterator(); it.hasNext();) {
                      if (!it.next().isAlive()) {
                         it.remove();
                      }
                   }
                   
-                  // create new jobs as allowed
+                  // step 2: create new jobs as allowed and available
                   synchronized (waiting) {
                      while (waiting.size() > 0 && running.size() < maxJobsParallel) {
                         PGFDataResource resource = waiting.remove(0);
@@ -490,62 +640,81 @@
                      }
                   }
                   
-                  // always sleep for a while
+                  // step 3: sleep for a while
                   try {
-                     sleep(2000);
+                     sleep(1000);
                   } catch (InterruptedException e) {}
                   
-                  // terminate controller if there is nothing to distribute
+                  // check to terminate controller if there is nothing to distribute
                   terminate = waiting.size() == 0;
                }
             }
          };
+         // start the controller
          controller.setDaemon(true);
          controller.setPriority(Thread.MAX_PRIORITY);
          controller.start();
       }
    }
-}
    
-private class PreloadingJob extends Thread {
-   private PGFDataResource resource;
-   private Exception error;
-   
-   public PreloadingJob (PGFDataResource resource) {
-      super("PGF Preloading - ".concat(resource.getName()));
-      setDaemon(true);
-      setPriority(MAX_PRIORITY-1);
-      this.resource = resource;
-   }
+   /**
+    * The Preloading Job performs retrieval of external data
+    * of a resource, given by its URL. After reading from a stream,
+    * the obtained data block is put into the <b>preloading cache</b> 
+    * of the resource manager, and the job gracefully exits.
+    * <p>The Job also performs issuing of three types of events
+    * concerning the loading phase. Preload-Started, Preload-Terminated
+    * and Preload-Failure. These events are available for the user at
+    * the resource manager's interface. A Preloading Job runs with a high
+    * priority of Thread.MAX_PRIORITY-1.
+    *  
+    */
+   private class PreloadingJob extends Thread {
+      private PGFDataResource resource;
+      
+      public PreloadingJob (PGFDataResource resource) {
+         super("PGF Preloading - ".concat(resource.getName()));
+         setDaemon(true);
+         setPriority(MAX_PRIORITY-1);
+         this.resource = resource;
+      }
 
-   @Override
-   public void run() {
-      try {
-         // issue started event
-         long h = System.currentTimeMillis(); 
-         firePreloadStartedEvent(resource, h);
+      @Override
+      public void run() {
+         try {
+            // issue started event
+            long h = System.currentTimeMillis(); 
+            firePreloadStartedEvent(resource, h);
 
-         // retrieve external data block and cache
-         InputStream in = resource.getResourceURL().openStream();
-         byte[] data = inputToByteBlock(in);
-         preloadCache.put(resource.getName(), data);
-         
-         // issue finished event
-         long j = System.currentTimeMillis(); 
-         fireResourcePreloadedEvent(resource, j, (int)(j-h));
-      } 
-      catch (Exception e) {
-         error = e;
-         e.printStackTrace();
-         firePreloadingFailureEvent(resource, e);
+            // retrieve external data block and cache
+            InputStream in = resource.getResourceURL().openStream();
+            byte[] data = inputToByteBlock(in);
+            preloadCache.put(resource.getName(), data);
+            
+            // issue finished event
+            long j = System.currentTimeMillis(); 
+            fireResourcePreloadedEvent(resource, j, (int)(j-h));
+         } 
+         catch (Exception e) {
+            long h = System.currentTimeMillis(); 
+            e.printStackTrace();
+            firePreloadingFailureEvent(resource, h, e);
+         }
+         setJobFinished();
       }
-   }
-   
-   public Exception getErrorException () {
-      return error;
-   }
-}
-   
+      
+   }  // PreloadingJob
+} // PreloadingManager
+
+/**
+ * Data cache for byte array data blocks referenced through
+ * a name string. The cache is realised through a <code>LinkedHashMap</code>
+ * instance whose aging method is driven in "access mode".  
+ * <p>The cache can be limited by number of entries or total stored data size
+ * or both. The initial capacity is ruled by the global value "initialCacheCapacity"
+ * of PGFResourceManagerImpl. The load factor is 0.66 which gives a small
+ * advantage to access speed. 
+ */
 private static class DataCache { 
    private LinkedHashMap<String, byte[]> cMap;
    private int maxEntries;
@@ -563,8 +732,10 @@
    {
       this.maxEntries = Math.max(0, maxEntries);
       this.maxDataSize = Math.max(0, maxData);
+      int capacity = this.maxEntries == 0 ? initialCacheCapacity :
+                     Math.min(initialCacheCapacity, this.maxEntries*2);
       
-      cMap = new LinkedHashMap<String, byte[]>( this.maxEntries * 2, (float)0.50, true )
+      cMap = new LinkedHashMap<String, byte[]>( capacity, (float)0.66, true )
       {
          @Override
          protected boolean removeEldestEntry(Entry<String, byte[]> eldest) {
@@ -689,18 +860,4 @@
    }
 }
 
-public synchronized void fireResourcePreloadedEvent(PGFDataResource resource, long time, int duration) {
-   // TODO fireResourcePreloadedEvent
-   
 }
-
-public synchronized void firePreloadStartedEvent(PGFDataResource resource, long time) {
-   // TODO Auto-generated method stub
-   
-}
-
-public synchronized void firePreloadingFailureEvent(PGFDataResource resource, Exception e) {
-   // TODO firePreloadingFailureEvent
-   
-}
-}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




petraframe-svn Mailing List for PetraGameFrame

petraframe-svn — SVN Commit Diff Archive