1   /**
2    * Logback: the reliable, generic, fast and flexible logging framework.
3    * Copyright (C) 1999-2015, QOS.ch. All rights reserved.
4    *
5    * This program and the accompanying materials are dual-licensed under
6    * either the terms of the Eclipse Public License v1.0 as published by
7    * the Eclipse Foundation
8    *
9    *   or (per the licensee's choosing)
10   *
11   * under the terms of the GNU Lesser General Public License version 2.1
12   * as published by the Free Software Foundation.
13   */
14  package ch.qos.logback.core.spi;
15  
16  import ch.qos.logback.core.CoreConstants;
17  
18  import java.util.Collection;
19  import java.util.Set;
20  
21  /**
22   * Interface for tracking various components by key. Components which have not
23   * been accessed for more than a user-specified duration are deemed stale and
24   * removed. Components can also be explicitly marked as having reached their
25   * {@link #endOfLife(String)} in which case they will linger for a few seconds
26   * and then be removed.
27   *
28   * @author Tommy Becker
29   * @author Ceki Gulcu
30   * @author David Roussel
31   *
32   * @since 1.0.12
33   */
34  public interface ComponentTracker<C> {
35  
36      /**
37       * The default timeout duration is 30 minutes
38       */
39      public final int DEFAULT_TIMEOUT = (int) (30 * 60 * CoreConstants.MILLIS_IN_ONE_SECOND); // 30 minutes
40  
41      /**
42       * By default an unlimited number of elements can be tracked.
43       */
44      int DEFAULT_MAX_COMPONENTS = Integer.MAX_VALUE;
45  
46      /**
47       * Returns the number of components tracked.
48       * 
49       * @return number of components
50       */
51      int getComponentCount();
52  
53      /**
54       * Find the component identified by 'key', without updating the timestamp.
55       * Returns null if no corresponding component could be found.
56       *
57       * @param key
58       * @return corresponding component, may be null
59       */
60      C find(String key);
61  
62      /**
63       * Get the component identified by 'key', updating its timestamp in the process.
64       * If the corresponding component could not be found, it is created.
65       *
66       * @param key
67       * @param timestamp
68       * @return
69       */
70      C getOrCreate(String key, long timestamp);
71  
72      /**
73       * Remove components which are deemed stale. Components which have not been
74       * accessed for more than a user-specified duration are deemed stale.
75       *
76       * <p>
77       * If the number of components exceeds, {@link #getComponentCount()}, components
78       * in excess will be removed.
79       * </p>
80       *
81       * <p>
82       * Depending on the component type, components will be cleared or stopped (as
83       * appropriate) right before removal.
84       * </p>
85       *
86       * @param now current time in milliseconds
87       */
88      void removeStaleComponents(long now);
89  
90      /**
91       * Mark component identified by 'key' as having reached its end-of-life.
92       * End-of-lifed components will linger for a few more seconds before being
93       * removed.
94       *
95       * @param key
96       */
97      void endOfLife(String key);
98  
99      /**
100      * Returns the collection of all components tracked by this instance.
101      * 
102      * @return collection of components
103      */
104     Collection<C> allComponents();
105 
106     /**
107      * Set of all keys in this tracker in no particular order.
108      *
109      * @return
110      */
111     Set<String> allKeys();
112 }