001/** 002 * Logback: the reliable, generic, fast and flexible logging framework. 003 * Copyright (C) 1999-2015, QOS.ch. All rights reserved. 004 * 005 * This program and the accompanying materials are dual-licensed under 006 * either the terms of the Eclipse Public License v1.0 as published by 007 * the Eclipse Foundation 008 * 009 * or (per the licensee's choosing) 010 * 011 * under the terms of the GNU Lesser General Public License version 2.1 012 * as published by the Free Software Foundation. 013 */ 014package ch.qos.logback.core.spi; 015 016import ch.qos.logback.core.CoreConstants; 017 018import java.util.Collection; 019import java.util.Set; 020 021/** 022 * Interface for tracking various components by key. Components which have not 023 * been accessed for more than a user-specified duration are deemed stale and 024 * removed. Components can also be explicitly marked as having reached their 025 * {@link #endOfLife(String)} in which case they will linger for a few seconds 026 * and then be removed. 027 * 028 * @author Tommy Becker 029 * @author Ceki Gulcu 030 * @author David Roussel 031 * 032 * @since 1.0.12 033 */ 034public interface ComponentTracker<C> { 035 036 /** 037 * The default timeout duration is 30 minutes 038 */ 039 public final int DEFAULT_TIMEOUT = (int) (30 * 60 * CoreConstants.MILLIS_IN_ONE_SECOND); // 30 minutes 040 041 /** 042 * By default an unlimited number of elements can be tracked. 043 */ 044 int DEFAULT_MAX_COMPONENTS = Integer.MAX_VALUE; 045 046 /** 047 * Returns the number of components tracked. 048 * 049 * @return number of components 050 */ 051 int getComponentCount(); 052 053 /** 054 * Find the component identified by 'key', without updating the timestamp. 055 * Returns null if no corresponding component could be found. 056 * 057 * @param key 058 * @return corresponding component, may be null 059 */ 060 C find(String key); 061 062 /** 063 * Get the component identified by 'key', updating its timestamp in the process. 064 * If the corresponding component could not be found, it is created. 065 * 066 * @param key 067 * @param timestamp 068 * @return 069 */ 070 C getOrCreate(String key, long timestamp); 071 072 /** 073 * Remove components which are deemed stale. Components which have not been 074 * accessed for more than a user-specified duration are deemed stale. 075 * 076 * <p> 077 * If the number of components exceeds, {@link #getComponentCount()}, components 078 * in excess will be removed. 079 * </p> 080 * 081 * <p> 082 * Depending on the component type, components will be cleared or stopped (as 083 * appropriate) right before removal. 084 * </p> 085 * 086 * @param now current time in milliseconds 087 */ 088 void removeStaleComponents(long now); 089 090 /** 091 * Mark component identified by 'key' as having reached its end-of-life. 092 * End-of-lifed components will linger for a few more seconds before being 093 * removed. 094 * 095 * @param key 096 */ 097 void endOfLife(String key); 098 099 /** 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}