001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.lang.management;
019:
020: /**
021: * <p>
022: * <code>MemoryPoolMXBean</code> is an interface used by the management
023: * system to access memory pool properties.
024: * </p>
025: * <p>
026: * <code>ObjectName</code> pattern: java.lang:type=MemoryPool,name=<i>pool_name</i>
027: * </p>
028: *
029: * @since 1.5
030: */
031: public interface MemoryPoolMXBean {
032: /**
033: * <p>
034: * The memory usage of the JVM's most recent attempt to recycle unused
035: * objects in this pool. If this feature is not supported, then
036: * <code>null</code> will be returned.
037: * </p>
038: *
039: * @return A {@link MemoryUsage} instance representing the most recent
040: * attempt to recycle unused objects; <code>null</code> may be
041: * returned to indicated this method is not supported.
042: */
043: MemoryUsage getCollectionUsage();
044:
045: /**
046: * <p>
047: * The collection usage threshold (in bytes) of this pool; the default is
048: * zero.
049: * </p>
050: *
051: * @return The collection usage threshold value.
052: * @throws UnsupportedOperationException if this is not supported.
053: * @see #isCollectionUsageThresholdSupported()
054: */
055: long getCollectionUsageThreshold();
056:
057: /**
058: * <p>
059: * The number of times the collection usage threshold has been reached or
060: * exceeded.
061: * </p>
062: *
063: * @return The number of times the collection usage threshold has been
064: * reached or exceeded.
065: * @throws UnsupportedOperationException if this is not supported.
066: * @see #isCollectionUsageThresholdSupported()
067: */
068: long getCollectionUsageThresholdCount();
069:
070: /**
071: * <p>
072: * The names of the memory managers that manage this pool; there will be at
073: * least one memory manager for each pool.
074: * </p>
075: *
076: * @return A <code>String[]</code> of memory manager names.
077: */
078: String[] getMemoryManagerNames();
079:
080: /**
081: * <p>
082: * The name of this memory pool.
083: * </p>
084: *
085: * @return The name of this memory pool.
086: */
087: String getName();
088:
089: /**
090: * <p>
091: * The peak memory usage of this pool since JVM startup or since the last
092: * reset of the peak.
093: * </p>
094: *
095: * @return A {@link MemoryUsage} instance representing the peak usage.
096: * @see #resetPeakUsage()
097: */
098: MemoryUsage getPeakUsage();
099:
100: /**
101: * <p>
102: * The memory type of this pool.
103: * </p>
104: *
105: * @return The pool's memory type.
106: */
107: MemoryType getType();
108:
109: /**
110: * <p>
111: * The approximate, current memory usage of this pool. This method will
112: * return <code>null</code> if the pool is invalid.
113: * </p>
114: *
115: * @return A {@link MemoryUsage} instance representing the current usage or
116: * <code>null</code> if the pool is invalid.
117: */
118: MemoryUsage getUsage();
119:
120: /**
121: * <p>
122: * The current usage threshold (in bytes) of this pool.
123: * </p>
124: *
125: * @return The current usage threshold.
126: * @throws UnsupportedOperationException if this is not supported.
127: * @see #isUsageThresholdSupported()
128: */
129: long getUsageThreshold();
130:
131: /**
132: * <p>
133: * The number of times the usage threshold has been met or exceeded.
134: * </p>
135: *
136: * @return The number of times the usage threshold has been met or exceeded.
137: * @throws UnsupportedOperationException if this is not supported.
138: * @see #isUsageThresholdSupported()
139: */
140: long getUsageThresholdCount();
141:
142: /**
143: * <p>
144: * Indicates whether or not the collection usage threshold has been met or
145: * exceeded after the most recent collection.
146: * </p>
147: *
148: * @return <code>true</code> if the collection usage threshold was met or
149: * exceeded, otherwise <code>false</code>.
150: * @throws UnsupportedOperationException if this is not supported.
151: * @see #isCollectionUsageThresholdSupported()
152: */
153: boolean isCollectionUsageThresholdExceeded();
154:
155: /**
156: * <p>
157: * Indicates whether or not this pool supports collection threshold
158: * monitoring.
159: * </p>
160: *
161: * @return <code>true</code> if supported, <code>false</code> otherwise.
162: */
163: boolean isCollectionUsageThresholdSupported();
164:
165: /**
166: * <p>
167: * Indicates whether or not the usage threshold is currently met or
168: * exceeded.
169: * </p>
170: *
171: * @return <code>true</code> if the usage threshold is met or exceeded,
172: * otherwise <code>false</code>.
173: * @throws UnsupportedOperationException if this is not supported.
174: * @see #isUsageThresholdSupported()
175: */
176: boolean isUsageThresholdExceeded();
177:
178: /**
179: * <p>
180: * Indicates whether or not usage threshold monitoring is supported.
181: * </p>
182: *
183: * @return <code>true</code> if supported, otherwise <code>false</code>.
184: */
185: boolean isUsageThresholdSupported();
186:
187: /**
188: * <p>
189: * Indicates whether or not the pool is currently valid. A memory pool may
190: * be removed by a JVM and become invalid.
191: * </p>
192: *
193: * @return <code>true</code> if the pool is valid, <code>false</code>
194: * otherwise.
195: */
196: boolean isValid();
197:
198: /**
199: * <p>
200: * Resets the peak memory usage to the current value.
201: * </p>
202: *
203: * @throws SecurityException if caller doesn't have
204: * <code>ManagementPermission("control")</code>.
205: */
206: void resetPeakUsage();
207:
208: /**
209: * <p>
210: * Sets the collection usage threshold (in bytes) for this memory pool.
211: * </p>
212: *
213: * @param threshold The new, non-negative threshold.
214: * @throws IllegalArgumentException if the new <code>threshold</code> is either negative
215: * or greater than the maximum memory allowed.
216: * @throws UnsupportedOperationException if this is not supported.
217: * @throws SecurityException if caller doesn't have
218: * <code>ManagementPermission("control")</code>.
219: */
220: void setCollectionUsageThreshold(long threshold);
221:
222: /**
223: * <p>
224: * Sets the usage threshold (in bytes) for this memory pool.
225: * </p>
226: *
227: * @param threshold The new, non-negative threshold.
228: * @throws IllegalArgumentException if the new <code>threshold</code> is either negative
229: * or greater than the maximum memory allowed.
230: * @throws UnsupportedOperationException if this is not supported.
231: * @throws SecurityException if caller doesn't have
232: * <code>ManagementPermission("control")</code>.
233: */
234: void setUsageThreshold(long threshold);
235: }
|