View Javadoc
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       * @return number of components
49       */
50      int getComponentCount();
51  
52      /**
53       * Find the component identified by 'key', without updating the timestamp. Returns null if no
54       * corresponding component could be found.
55       *
56       * @param key
57       * @return corresponding component, may be null
58       */
59      C find(String key);
60  
61      /**
62       * Get the component identified by 'key', updating its timestamp in the
63       * process. If the corresponding component could not be found, it is created.
64       *
65       * @param key
66       * @param timestamp
67       * @return
68       */
69      C getOrCreate(String key, long timestamp);
70  
71      /**
72       * Remove components which are deemed stale. Components which have not
73       * been accessed for more than a user-specified duration are deemed stale.
74       *
75       * <p>If the number of components exceeds, {@link #getComponentCount()},
76       * components in excess will be removed.</p>
77       *
78       * <p>Depending on the component type, components will be cleared or stopped
79       * (as appropriate) right before removal.</p>
80       *
81       * @param now  current time in milliseconds
82       */
83      void removeStaleComponents(long now);
84  
85      /**
86       * Mark component identified by 'key' as having reached its end-of-life. End-of-lifed
87       * components will linger for a few more seconds before being removed.
88       *
89       * @param key
90       */
91      void endOfLife(String key);
92  
93      /**
94       * Returns the collection of all components tracked by this instance.
95       * @return  collection of components
96       */
97      Collection<C> allComponents();
98  
99      /**
100      * Set of all keys in this tracker in no particular order.
101      *
102      * @return
103      */
104     Set<String> allKeys();
105 }