CultureMemoryCell


1   /*
2    * This file is part of JGAP.
3    *
4    * JGAP offers a dual license model containing the LGPL as well as the MPL.
5    *
6    * For licencing information please see the file license.txt included with JGAP
7    * or have a look at the top of class org.jgap.Chromosome which representatively
8    * includes the JGAP license policy applicable for any file delivered with JGAP.
9    */
10  package org.jgap.distr;
11  
12  import java.io.*;
13  import java.util.*;
14  import org.apache.commons.lang.builder.*;
15  
16  /**
17   * Represents a memory cell used within {@link org.jgap.distr.Culture}, a
18   * special form of memory.
19   * <P>
20   * CultureMemoryCell also stores metadata along with the value-to-store, like
21   * date/time of setting a value, change history.
22   *
23   * @author Klaus Meffert
24   * @since 2.3
25   */
26  public class CultureMemoryCell
27      implements Serializable, Comparable   {
28    /** String containing the CVS revision. Read out via reflection!*/
29    private final static String   CVS_REVISION = "$Revision: 1.12 $";
30  
31    /**
32     * Informative name of the memory cell (optional)
33     */
34    private String   m_name;
35  
36    /**
37     * Version of the memory value, i.e. how many times has setValue(..) been
38     * called)? First version (no value assigned) is zero, second version (first
39     * time a value is assigned to the memory) is 1 etc.
40     */
41    private int m_version;
42  
43    /**
44     * Value of the memory cell
45     */
46    private Object   m_value;
47  
48    /**
49     * How many times has the memory cell been read out?
50     */
51    private int m_readAccessed;
52  
53    /**
54     * How many historical values should be kept for evaluation purposes?
55     * Values less than one turn history feature off
56     */
57    private int m_historySize;
58  
59    private int m_internalHistorySize;
60  
61    /**
62     * If history logging turned off, we need to keep the prior version for
63     * evaluation purpose, e.g. see getReadAccessedCurrentVersion
64     */
65    private CultureMemoryCell m_previousVersion;
66  
67    /**
68     * History of memory values
69     */
70    private List m_history;
71  
72    /**
73     * Time in milliseconds when the version number is incremented (e.g. when
74     * setting the value of the cell)
75     */
76    private long m_dateTimeVersion;
77  
78    /**
79     * Default constructor.
80     *
81     * @author Klaus Meffert
82     * @since 2.3
83     */
84    public CultureMemoryCell() {
85      this(null);
86    }
87  
88    /**
89     * Sets history size to 3.
90     * @param a_name informative name of the memory cell
91     *
92     * @author Klaus Meffert
93     * @since 2.3
94     */
95    public CultureMemoryCell(final String   a_name) {
96      this(a_name, 3);
97    }
98  
99    /**
100    * Allows to freely specify informative name of memory cell as well as size
101    * of history to keep.
102    * @param a_name informative name of the memory cell
103    * @param a_historySize size of history to keep. Use values less than 1 for
104    * turning history logging off
105    *
106    * @author Klaus Meffert
107    * @since 2.3
108    */
109   public CultureMemoryCell(final String   a_name, final int a_historySize) {
110     setHistorySize(a_historySize);
111     m_history = new Vector(getHistorySize());
112     setName(a_name);
113   }
114 
115   /**
116    * Sets the informative name of the memory cell.
117    * @param a_name informative name
118    *
119    * @author Klaus Meffert
120    * @since 2.3
121    */
122   public void setName(final String   a_name) {
123     m_name = a_name;
124   }
125 
126   /**
127    * @return informative name of the memory cell
128    *
129    * @author Klaus Meffert
130    * @since 2.3
131    */
132   public String   getName() {
133     return m_name;
134   }
135 
136   /**
137    * Sets a new memory value.
138    * @param a_value the memory value to set
139    *
140    * @author Klaus Meffert
141    * @since 2.3
142    */
143   public void setValue(final Object   a_value) {
144     if (m_historySize > 0) {
145       keepHistory(a_value, getVersion(), getName());
146     }
147     else {
148       m_previousVersion = getNewInstance(m_value, getVersion(),
149           getName());
150     }
151     m_value = a_value;
152     incrementVersion();
153   }
154 
155   /**
156    * Convenience method to store a primitive double easily.
157    *
158    * @param a_value double value to store
159    *
160    * @author Klaus Meffert
161    * @since 2.3
162    */
163   public void setDouble(final double a_value) {
164     setValue(new Double  (a_value));
165   }
166 
167   /**
168    * Convenience method to retrieve a primitive double value from memory
169    * easily. Here a ClassCastException could occur!
170    * @return double value representing current memory value
171    *
172    * @author Klaus Meffert
173    * @since 2.3
174    */
175   public double getCurrentValueAsDouble() {
176     return ( (Double  ) getCurrentValue()).doubleValue();
177   }
178 
179   /**
180    * @return current memory value
181    *
182    * @author Klaus Meffert
183    * @since 2.3
184    */
185   public Object   getCurrentValue() {
186     m_readAccessed++;
187     return m_value;
188   }
189 
190   /**
191    * @return list of most recent entries (except current entry). The item at
192    * index 0 is the oldest, the item at highest index is the youngest one.
193    *
194    * @author Klaus Meffert
195    * @since 2.3
196    */
197   public List getHistory() {
198     return m_history;
199   }
200 
201   /**
202    * @return version of memory value, read only
203    *
204    * @author Klaus Meffert
205    * @since 2.3
206    */
207   public int getVersion() {
208     return m_version;
209   }
210 
211   /**
212    * Increment version number and keep track of current time.
213    *
214    * @author Klaus Meffert
215    * @since 2.3
216    */
217   protected void incrementVersion() {
218     m_version++;
219     // Memorize current time.
220     m_dateTimeVersion = System.currentTimeMillis();
221   }
222 
223   /**
224    * Puts an entry into history. Stores all information as a new
225    * CultureMemoryCell instance.
226    *
227    * @param a_value memory value to store
228    * @param a_version version of the value
229    * @param a_name name to store
230    *
231    * @author Klaus Meffert
232    * @since 2.3
233    */
234   protected void keepHistory(final Object   a_value, final int a_version,
235                              final String   a_name) {
236     trimHistory(m_historySize - 1);
237     // simply add a new instance of CultureMemoryCell for keeping history track
238     CultureMemoryCell cell = getNewInstance(a_value, a_version, a_name);
239     cell.m_internalHistorySize = m_historySize;
240     m_history.add(cell);
241   }
242 
243   /**
244    * Creates a new instance of CultureMemoryCell preset with the given
245    * parameters. Used for creating history entries.
246    *
247    * @param a_value memory value to store
248    * @param a_version version of the value
249    * @param a_name name to store
250    * @return new instance of CultureMemoryCell
251    *
252    * @author Klaus Meffert
253    * @since 2.3
254    */
255   protected CultureMemoryCell getNewInstance(final Object   a_value,
256       final int a_version,
257       final String   a_name) {
258     // DON'T USE SETTERS IN HERE BECAUSE OF ENDLESS LOOPS!
259     CultureMemoryCell cell = new CultureMemoryCell(a_name, 0);
260     cell.m_value = a_value;
261     cell.m_version = a_version;
262     return cell;
263   }
264 
265   /**
266    * @return number of times the memory cell has been read accessed
267    *
268    * @author Klaus Meffert
269    * @since 2.3
270    */
271   public int getReadAccessed() {
272     return m_readAccessed;
273   }
274 
275   /**
276    * @return number of read accesses since current value has been set.
277    * Calculated by subtracting number of read accesses for prior version from
278    * total number of read accesses
279    *
280    * @author Klaus Meffert
281    * @since 2.3
282    */
283   public int getReadAccessedCurrentVersion() {
284     if (m_historySize < 1) {
285       // Use internal (simple/atomic) history.
286       // -------------------------------------
287       return getReadAccessed() - m_previousVersion.getReadAccessed();
288     }
289     else {
290       // Use sophisticated history (list).
291       // ---------------------------------
292       CultureMemoryCell cell = (CultureMemoryCell) m_history.get(
293           m_history.size() - 1);
294       return getReadAccessed() - cell.getReadAccessed();
295     }
296   }
297 
298   /**
299    * Sets the size of the history and scales down the history log it is larger
300    * than the given size.
301    * @param a_size new size of the history log = how many entries to store
302    *
303    * @author Klaus Meffert
304    * @since 2.3
305    */
306   public void setHistorySize(final int a_size) {
307     if (getHistory() != null && a_size > getHistory().size()) {
308       trimHistory(a_size);
309       m_historySize = a_size;
310     }
311     else if (a_size < 0) {
312       m_historySize = 0;
313     }
314     else {
315       m_historySize = a_size;
316     }
317   }
318 
319   /**
320    * Trims the history to the given size.
321    * @param a_size new size of history
322    *
323    * @author Klaus Meffert
324    * @since 2.3
325    */
326   protected void trimHistory(final int a_size) {
327     // trim length of history
328     while (m_history.size() > a_size) {
329       // remove one entry (always the first one = oldest one)
330       m_history.remove(0);
331     }
332   }
333 
334   /**
335    * @return size of the history
336    *
337    * @author Klaus Meffert
338    * @since 2.3
339    */
340   public int getHistorySize() {
341     return m_historySize;
342   }
343 
344   /**
345    * @return String representation of the cultural memory cell including all
346    * important information (also history log).
347    *
348    * @author Klaus Meffert
349    * @since 2.3
350    */
351   public String   toString() {
352     StringBuffer   result = new StringBuffer  ();
353     toStringRecursive(result, getHistorySize());
354     return result.toString();
355   }
356 
357   /**
358    * Recursive part of toString().
359    * @param a_result gathered result so far and modified here
360    * @param a_historySize history size just for information purpose
361    *
362    * @author Klaus Meffert
363    * @since 2.3
364    */
365   protected void toStringRecursive(StringBuffer   a_result,
366                                    final int a_historySize) {
367     List history = getHistory();
368     a_result.append("[Name:" + getName() + ";");
369     a_result.append("Value:" + m_value + ";"); //not getCurrentValue()!
370     a_result.append("Version:" + getVersion() + ";");
371     a_result.append("Read accessed:" + getReadAccessed() + ";");
372     a_result.append("History Size:" + a_historySize + ";");
373     a_result.append("History:[");
374     for (int i = 0; i < history.size(); i++) {
375       if (i > 0) {
376         a_result.append(";");
377       }
378       CultureMemoryCell cell = (CultureMemoryCell) history.get(i);
379       // do recursive call
380       cell.toStringRecursive(a_result, cell.m_internalHistorySize);
381       a_result.append("]");
382     }
383     a_result.append("]");
384   }
385 
386   /**
387    * @return time in milliseconds when the current version has been created
388    *
389    * @author Klaus Meffert
390    * @since 3.0
391    */
392   public long getVersionTimeMilliseconds() {
393     return m_dateTimeVersion;
394   }
395 
396   /**
397    * The equals-method.
398    * @param a_other the other object to compare
399    * @return true if the objects are regarded as equal
400    *
401    * @author Klaus Meffert
402    * @since 3.0
403    */
404   public boolean equals(Object   a_other) {
405     try {
406       return compareTo(a_other) == 0;
407     } catch (ClassCastException   cex) {
408       return false;
409     }
410   }
411 
412   /**
413    * The compareTo-method.
414    * @param a_other the other object to compare
415    * @return -1, 0, 1
416    *
417    * @author Klaus Meffert
418    * @since 3.0
419    */
420   public int compareTo(Object   a_other) {
421     CultureMemoryCell other = (CultureMemoryCell) a_other;
422     if (other == null) {
423       return 1;
424     }
425     return new CompareToBuilder()
426         .append(m_value, other.m_value)
427         .append(m_version, other.m_version)
428         .append(m_historySize, other.m_historySize)
429         .toComparison();
430   }
431 }
432
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags