20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang.management; 27 28 /** 29 * The management interface for a memory pool. A memory pool 30 * represents the memory resource managed by the Java virtual machine 31 * and is managed by one or more {@link MemoryManagerMXBean memory managers}. 32 * 33 * <p> A Java virtual machine has one or more instances of the 34 * implementation class of this interface. An instance 35 * implementing this interface is 36 * an <a href="ManagementFactory.html#MXBean">MXBean</a> 37 * that can be obtained by calling 38 * the {@link ManagementFactory#getMemoryPoolMXBeans} method or 39 * from the {@link ManagementFactory#getPlatformMBeanServer 40 * platform <tt>MBeanServer</tt>} method. 41 * 42 * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for 43 * a memory pool within an <tt>MBeanServer</tt> is: 44 * <blockquote> 45 * {@link ManagementFactory#MEMORY_POOL_MXBEAN_DOMAIN_TYPE 46 * <tt>java.lang:type=MemoryPool</tt>}<tt>,name=</tt><i>pool's name</i> 47 * </blockquote> 48 * 49 * It can be obtained by calling the 50 * {@link PlatformManagedObject#getObjectName} method. 51 * 52 * <h3>Memory Type</h3> 53 * <p>The Java virtual machine has a heap for object allocation and also 54 * maintains non-heap memory for the method area and the Java virtual 55 * machine execution. The Java virtual machine can have one or more 56 * memory pools. Each memory pool represents a memory area 57 * of one of the following types: 58 * <ul> 59 * <li>{@link MemoryType#HEAP heap}</li> 60 * <li>{@link MemoryType#NON_HEAP non-heap}</li> 61 * </ul> 62 * 63 * <h3>Memory Usage Monitoring</h3> 64 * 65 * A memory pool has the following attributes: 66 * <ul> 219 * } catch (InterruptException e) { 220 * .... 221 * } 222 * } 223 * 224 * // Do some processing such as check for memory usage 225 * // and issue a warning 226 * .... 227 * 228 * // Gets the current threshold count. The busy loop will then 229 * // ignore any crossing of threshold happens during the processing. 230 * prevCrossingCount = pool.getUsageThresholdCount(); 231 * } 232 * </pre><hr> 233 * </li> 234 * <li><a name="ThresholdNotification"><b>Usage Threshold Notifications</b></a> 235 * <p> 236 * Usage threshold notification will be emitted by {@link MemoryMXBean}. 237 * When the Java virtual machine detects that the memory usage of 238 * a memory pool has reached or exceeded the usage threshold 239 * the virtual machine will trigger the <tt>MemoryMXBean</tt> to emit an 240 * {@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED 241 * usage threshold exceeded notification}. 242 * Another usage threshold exceeded notification will not be 243 * generated until the usage has fallen below the threshold and 244 * then exceeded it again. 245 * <p> 246 * Below is an example code implementing the same logic as the 247 * first example above but using the usage threshold notification 248 * mechanism to detect low memory conditions instead of polling. 249 * In this example code, upon receiving notification, the notification 250 * listener notifies another thread to perform the actual action 251 * such as to redistribute outstanding tasks, stop receiving tasks, 252 * or resume receiving tasks. 253 * The <tt>handleNotification</tt> method should be designed to 254 * do a very minimal amount of work and return without delay to avoid 255 * causing delay in delivering subsequent notifications. Time-consuming 256 * actions should be performed by a separate thread. 257 * The notification listener may be invoked by multiple threads 258 * concurrently; so the tasks performed by the listener 259 * should be properly synchronized. 260 * 261 * <pre> 262 * class MyListener implements javax.management.NotificationListener { 263 * public void handleNotification(Notification notification, Object handback) { 264 * String notifType = notification.getType(); 265 * if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED)) { 266 * // potential low memory, notify another thread 267 * // to redistribute outstanding tasks to other VMs 268 * // and stop receiving new tasks. 269 * lowMemory = true; 270 * notifyAnotherThread(lowMemory); 271 * } 272 * } 273 * } 274 * 275 * // Register MyListener with MemoryMXBean 276 * MemoryMXBean mbean = ManagementFactory.getMemoryMXBean(); 277 * NotificationEmitter emitter = (NotificationEmitter) mbean; 278 * MyListener listener = new MyListener(); 279 * emitter.addNotificationListener(listener, null, null); 280 * 281 * // Assume this pool supports a usage threshold. 282 * // Set the threshold to myThreshold above which no new tasks 283 * // should be taken. 284 * pool.setUsageThreshold(myThreshold); 285 * 286 * // Usage threshold detection is enabled and notification will be 287 * // handled by MyListener. Continue for other processing. 288 * .... 289 * 290 * </pre> 291 * <hr> 292 * <p> 293 * There is no guarantee about when the <tt>MemoryMXBean</tt> will emit 294 * a threshold notification and when the notification will be delivered. 295 * When a notification listener is invoked, the memory usage of 296 * the memory pool may have crossed the usage threshold more 297 * than once. 298 * The {@link MemoryNotificationInfo#getCount} method returns the number 299 * of times that the memory usage has crossed the usage threshold 300 * at the point in time when the notification was constructed. 301 * It can be compared with the current usage threshold count returned 302 * by the {@link #getUsageThresholdCount} method to determine if 303 * such situation has occurred. 304 * </li> 305 * </ol> 306 * 307 * <h3><a name="CollectionThreshold">4. Collection Usage Threshold</a></h3> 308 * 309 * Collection usage threshold is a manageable attribute only applicable 310 * to some garbage-collected memory pools. 311 * After a Java virtual machine has expended effort in reclaiming memory 312 * space by recycling unused objects in a memory pool at garbage collection 313 * time, some number of bytes in the memory pools that are garbaged 357 * JMX Specification.</a> 358 * @see <a href="package-summary.html#examples"> 359 * Ways to Access MXBeans</a> 360 * 361 * @author Mandy Chung 362 * @since 1.5 363 */ 364 public interface MemoryPoolMXBean extends PlatformManagedObject { 365 /** 366 * Returns the name representing this memory pool. 367 * 368 * @return the name of this memory pool. 369 */ 370 public String getName(); 371 372 /** 373 * Returns the type of this memory pool. 374 * 375 * <p> 376 * <b>MBeanServer access</b>:<br> 377 * The mapped type of <tt>MemoryType</tt> is <tt>String</tt> 378 * and the value is the name of the <tt>MemoryType</tt>. 379 * 380 * @return the type of this memory pool. 381 */ 382 public MemoryType getType(); 383 384 /** 385 * Returns an estimate of the memory usage of this memory pool. 386 * This method returns <tt>null</tt> 387 * if this memory pool is not valid (i.e. no longer exists). 388 * 389 * <p> 390 * This method requests the Java virtual machine to make 391 * a best-effort estimate of the current memory usage of this 392 * memory pool. For some memory pools, this method may be an 393 * expensive operation that requires some computation to determine 394 * the estimate. An implementation should document when 395 * this is the case. 396 * 397 * <p>This method is designed for use in monitoring system 398 * memory usage and detecting low memory condition. 399 * 400 * <p> 401 * <b>MBeanServer access</b>:<br> 402 * The mapped type of <tt>MemoryUsage</tt> is 403 * <tt>CompositeData</tt> with attributes as specified in 404 * {@link MemoryUsage#from MemoryUsage}. 405 * 406 * @return a {@link MemoryUsage} object; or <tt>null</tt> if 407 * this pool not valid. 408 */ 409 public MemoryUsage getUsage(); 410 411 /** 412 * Returns the peak memory usage of this memory pool since the 413 * Java virtual machine was started or since the peak was reset. 414 * This method returns <tt>null</tt> 415 * if this memory pool is not valid (i.e. no longer exists). 416 * 417 * <p> 418 * <b>MBeanServer access</b>:<br> 419 * The mapped type of <tt>MemoryUsage</tt> is 420 * <tt>CompositeData</tt> with attributes as specified in 421 * {@link MemoryUsage#from MemoryUsage}. 422 * 423 * @return a {@link MemoryUsage} object representing the peak 424 * memory usage; or <tt>null</tt> if this pool is not valid. 425 * 426 */ 427 public MemoryUsage getPeakUsage(); 428 429 /** 430 * Resets the peak memory usage statistic of this memory pool 431 * to the current memory usage. 432 * 433 * @throws java.lang.SecurityException if a security manager 434 * exists and the caller does not have 435 * ManagementPermission("control"). 436 */ 437 public void resetPeakUsage(); 438 439 /** 440 * Tests if this memory pool is valid in the Java virtual 441 * machine. A memory pool becomes invalid once the Java virtual 442 * machine removes it from the memory system. 443 * 444 * @return <tt>true</tt> if the memory pool is valid in the running 445 * Java virtual machine; 446 * <tt>false</tt> otherwise. 447 */ 448 public boolean isValid(); 449 450 /** 451 * Returns the name of memory managers that manages this memory pool. 452 * Each memory pool will be managed by at least one memory manager. 453 * 454 * @return an array of <tt>String</tt> objects, each is the name of 455 * a memory manager managing this memory pool. 456 */ 457 public String[] getMemoryManagerNames(); 458 459 /** 460 * Returns the usage threshold value of this memory pool in bytes. 461 * Each memory pool has a platform-dependent default threshold value. 462 * The current usage threshold can be changed via the 463 * {@link #setUsageThreshold setUsageThreshold} method. 464 * 465 * @return the usage threshold value of this memory pool in bytes. 466 * 467 * @throws UnsupportedOperationException if this memory pool 468 * does not support a usage threshold. 469 * 470 * @see #isUsageThresholdSupported 471 */ 472 public long getUsageThreshold(); 473 474 /** 475 * Sets the threshold of this memory pool to the given <tt>threshold</tt> 476 * value if this memory pool supports the usage threshold. 477 * The usage threshold crossing checking is enabled in this memory pool 478 * if the threshold is set to a positive value. 479 * The usage threshold crossing checking is disabled 480 * if it is set to zero. 481 * 482 * @param threshold the new threshold value in bytes. Must be non-negative. 483 * 484 * @throws IllegalArgumentException if <tt>threshold</tt> is negative 485 * or greater than the maximum amount of memory for 486 * this memory pool if defined. 487 * 488 * @throws UnsupportedOperationException if this memory pool 489 * does not support a usage threshold. 490 * 491 * @throws java.lang.SecurityException if a security manager 492 * exists and the caller does not have 493 * ManagementPermission("control"). 494 * 495 * @see #isUsageThresholdSupported 496 * @see <a href="#UsageThreshold">Usage threshold</a> 497 */ 498 public void setUsageThreshold(long threshold); 499 500 /** 501 * Tests if the memory usage of this memory pool 502 * reaches or exceeds its usage threshold value. 503 * 504 * @return <tt>true</tt> if the memory usage of 505 * this memory pool reaches or exceeds the threshold value; 506 * <tt>false</tt> otherwise. 507 * 508 * @throws UnsupportedOperationException if this memory pool 509 * does not support a usage threshold. 510 */ 511 public boolean isUsageThresholdExceeded(); 512 513 /** 514 * Returns the number of times that the memory usage has crossed 515 * the usage threshold. 516 * 517 * @return the number of times that the memory usage 518 * has crossed its usage threshold value. 519 * 520 * @throws UnsupportedOperationException if this memory pool 521 * does not support a usage threshold. 522 */ 523 public long getUsageThresholdCount(); 524 525 /** 526 * Tests if this memory pool supports usage threshold. 527 * 528 * @return <tt>true</tt> if this memory pool supports usage threshold; 529 * <tt>false</tt> otherwise. 530 */ 531 public boolean isUsageThresholdSupported(); 532 533 /** 534 * Returns the collection usage threshold value of this memory pool 535 * in bytes. The default value is zero. The collection usage 536 * threshold can be changed via the 537 * {@link #setCollectionUsageThreshold setCollectionUsageThreshold} method. 538 * 539 * @return the collection usage threshold of this memory pool in bytes. 540 * 541 * @throws UnsupportedOperationException if this memory pool 542 * does not support a collection usage threshold. 543 * 544 * @see #isCollectionUsageThresholdSupported 545 */ 546 public long getCollectionUsageThreshold(); 547 548 /** 549 * Sets the collection usage threshold of this memory pool to 550 * the given <tt>threshold</tt> value. 551 * When this threshold is set to positive, the Java virtual machine 552 * will check the memory usage at its best appropriate time after it has 553 * expended effort in recycling unused objects in this memory pool. 554 * <p> 555 * The collection usage threshold crossing checking is enabled 556 * in this memory pool if the threshold is set to a positive value. 557 * The collection usage threshold crossing checking is disabled 558 * if it is set to zero. 559 * 560 * @param threshold the new collection usage threshold value in bytes. 561 * Must be non-negative. 562 * 563 * @throws IllegalArgumentException if <tt>threshold</tt> is negative 564 * or greater than the maximum amount of memory for 565 * this memory pool if defined. 566 * 567 * @throws UnsupportedOperationException if this memory pool 568 * does not support a collection usage threshold. 569 * 570 * @throws java.lang.SecurityException if a security manager 571 * exists and the caller does not have 572 * ManagementPermission("control"). 573 * 574 * @see #isCollectionUsageThresholdSupported 575 * @see <a href="#CollectionThreshold">Collection usage threshold</a> 576 */ 577 public void setCollectionUsageThreshold(long threshold); 578 579 /** 580 * Tests if the memory usage of this memory pool after 581 * the most recent collection on which the Java virtual 582 * machine has expended effort has reached or 583 * exceeded its collection usage threshold. 584 * This method does not request the Java virtual 585 * machine to perform any garbage collection other than its normal 586 * automatic memory management. 587 * 588 * @return <tt>true</tt> if the memory usage of this memory pool 589 * reaches or exceeds the collection usage threshold value 590 * in the most recent collection; 591 * <tt>false</tt> otherwise. 592 * 593 * @throws UnsupportedOperationException if this memory pool 594 * does not support a usage threshold. 595 */ 596 public boolean isCollectionUsageThresholdExceeded(); 597 598 /** 599 * Returns the number of times that the Java virtual machine 600 * has detected that the memory usage has reached or 601 * exceeded the collection usage threshold. 602 * 603 * @return the number of times that the memory 604 * usage has reached or exceeded the collection usage threshold. 605 * 606 * @throws UnsupportedOperationException if this memory pool 607 * does not support a collection usage threshold. 608 * 609 * @see #isCollectionUsageThresholdSupported 610 */ 611 public long getCollectionUsageThresholdCount(); 612 613 /** 614 * Returns the memory usage after the Java virtual machine 615 * most recently expended effort in recycling unused objects 616 * in this memory pool. 617 * This method does not request the Java virtual 618 * machine to perform any garbage collection other than its normal 619 * automatic memory management. 620 * This method returns <tt>null</tt> if the Java virtual 621 * machine does not support this method. 622 * 623 * <p> 624 * <b>MBeanServer access</b>:<br> 625 * The mapped type of <tt>MemoryUsage</tt> is 626 * <tt>CompositeData</tt> with attributes as specified in 627 * {@link MemoryUsage#from MemoryUsage}. 628 * 629 * @return a {@link MemoryUsage} representing the memory usage of 630 * this memory pool after the Java virtual machine most recently 631 * expended effort in recycling unused objects; 632 * <tt>null</tt> if this method is not supported. 633 */ 634 public MemoryUsage getCollectionUsage(); 635 636 /** 637 * Tests if this memory pool supports a collection usage threshold. 638 * 639 * @return <tt>true</tt> if this memory pool supports the 640 * collection usage threshold; <tt>false</tt> otherwise. 641 */ 642 public boolean isCollectionUsageThresholdSupported(); 643 } | 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang.management; 27 28 /** 29 * The management interface for a memory pool. A memory pool 30 * represents the memory resource managed by the Java virtual machine 31 * and is managed by one or more {@link MemoryManagerMXBean memory managers}. 32 * 33 * <p> A Java virtual machine has one or more instances of the 34 * implementation class of this interface. An instance 35 * implementing this interface is 36 * an <a href="ManagementFactory.html#MXBean">MXBean</a> 37 * that can be obtained by calling 38 * the {@link ManagementFactory#getMemoryPoolMXBeans} method or 39 * from the {@link ManagementFactory#getPlatformMBeanServer 40 * platform MBeanServer} method. 41 * 42 * <p>The {@code ObjectName} for uniquely identifying the MXBean for 43 * a memory pool within an {@code MBeanServer} is: 44 * <blockquote> 45 * {@link ManagementFactory#MEMORY_POOL_MXBEAN_DOMAIN_TYPE 46 * java.lang:type=MemoryPool}{@code ,name=}<i>pool's name</i> 47 * </blockquote> 48 * 49 * It can be obtained by calling the 50 * {@link PlatformManagedObject#getObjectName} method. 51 * 52 * <h3>Memory Type</h3> 53 * <p>The Java virtual machine has a heap for object allocation and also 54 * maintains non-heap memory for the method area and the Java virtual 55 * machine execution. The Java virtual machine can have one or more 56 * memory pools. Each memory pool represents a memory area 57 * of one of the following types: 58 * <ul> 59 * <li>{@link MemoryType#HEAP heap}</li> 60 * <li>{@link MemoryType#NON_HEAP non-heap}</li> 61 * </ul> 62 * 63 * <h3>Memory Usage Monitoring</h3> 64 * 65 * A memory pool has the following attributes: 66 * <ul> 219 * } catch (InterruptException e) { 220 * .... 221 * } 222 * } 223 * 224 * // Do some processing such as check for memory usage 225 * // and issue a warning 226 * .... 227 * 228 * // Gets the current threshold count. The busy loop will then 229 * // ignore any crossing of threshold happens during the processing. 230 * prevCrossingCount = pool.getUsageThresholdCount(); 231 * } 232 * </pre><hr> 233 * </li> 234 * <li><a name="ThresholdNotification"><b>Usage Threshold Notifications</b></a> 235 * <p> 236 * Usage threshold notification will be emitted by {@link MemoryMXBean}. 237 * When the Java virtual machine detects that the memory usage of 238 * a memory pool has reached or exceeded the usage threshold 239 * the virtual machine will trigger the {@code MemoryMXBean} to emit an 240 * {@link MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED 241 * usage threshold exceeded notification}. 242 * Another usage threshold exceeded notification will not be 243 * generated until the usage has fallen below the threshold and 244 * then exceeded it again. 245 * <p> 246 * Below is an example code implementing the same logic as the 247 * first example above but using the usage threshold notification 248 * mechanism to detect low memory conditions instead of polling. 249 * In this example code, upon receiving notification, the notification 250 * listener notifies another thread to perform the actual action 251 * such as to redistribute outstanding tasks, stop receiving tasks, 252 * or resume receiving tasks. 253 * The {@code handleNotification} method should be designed to 254 * do a very minimal amount of work and return without delay to avoid 255 * causing delay in delivering subsequent notifications. Time-consuming 256 * actions should be performed by a separate thread. 257 * The notification listener may be invoked by multiple threads 258 * concurrently; so the tasks performed by the listener 259 * should be properly synchronized. 260 * 261 * <pre> 262 * class MyListener implements javax.management.NotificationListener { 263 * public void handleNotification(Notification notification, Object handback) { 264 * String notifType = notification.getType(); 265 * if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED)) { 266 * // potential low memory, notify another thread 267 * // to redistribute outstanding tasks to other VMs 268 * // and stop receiving new tasks. 269 * lowMemory = true; 270 * notifyAnotherThread(lowMemory); 271 * } 272 * } 273 * } 274 * 275 * // Register MyListener with MemoryMXBean 276 * MemoryMXBean mbean = ManagementFactory.getMemoryMXBean(); 277 * NotificationEmitter emitter = (NotificationEmitter) mbean; 278 * MyListener listener = new MyListener(); 279 * emitter.addNotificationListener(listener, null, null); 280 * 281 * // Assume this pool supports a usage threshold. 282 * // Set the threshold to myThreshold above which no new tasks 283 * // should be taken. 284 * pool.setUsageThreshold(myThreshold); 285 * 286 * // Usage threshold detection is enabled and notification will be 287 * // handled by MyListener. Continue for other processing. 288 * .... 289 * 290 * </pre> 291 * <hr> 292 * <p> 293 * There is no guarantee about when the {@code MemoryMXBean} will emit 294 * a threshold notification and when the notification will be delivered. 295 * When a notification listener is invoked, the memory usage of 296 * the memory pool may have crossed the usage threshold more 297 * than once. 298 * The {@link MemoryNotificationInfo#getCount} method returns the number 299 * of times that the memory usage has crossed the usage threshold 300 * at the point in time when the notification was constructed. 301 * It can be compared with the current usage threshold count returned 302 * by the {@link #getUsageThresholdCount} method to determine if 303 * such situation has occurred. 304 * </li> 305 * </ol> 306 * 307 * <h3><a name="CollectionThreshold">4. Collection Usage Threshold</a></h3> 308 * 309 * Collection usage threshold is a manageable attribute only applicable 310 * to some garbage-collected memory pools. 311 * After a Java virtual machine has expended effort in reclaiming memory 312 * space by recycling unused objects in a memory pool at garbage collection 313 * time, some number of bytes in the memory pools that are garbaged 357 * JMX Specification.</a> 358 * @see <a href="package-summary.html#examples"> 359 * Ways to Access MXBeans</a> 360 * 361 * @author Mandy Chung 362 * @since 1.5 363 */ 364 public interface MemoryPoolMXBean extends PlatformManagedObject { 365 /** 366 * Returns the name representing this memory pool. 367 * 368 * @return the name of this memory pool. 369 */ 370 public String getName(); 371 372 /** 373 * Returns the type of this memory pool. 374 * 375 * <p> 376 * <b>MBeanServer access</b>:<br> 377 * The mapped type of {@code MemoryType} is {@code String} 378 * and the value is the name of the {@code MemoryType}. 379 * 380 * @return the type of this memory pool. 381 */ 382 public MemoryType getType(); 383 384 /** 385 * Returns an estimate of the memory usage of this memory pool. 386 * This method returns {@code null} 387 * if this memory pool is not valid (i.e. no longer exists). 388 * 389 * <p> 390 * This method requests the Java virtual machine to make 391 * a best-effort estimate of the current memory usage of this 392 * memory pool. For some memory pools, this method may be an 393 * expensive operation that requires some computation to determine 394 * the estimate. An implementation should document when 395 * this is the case. 396 * 397 * <p>This method is designed for use in monitoring system 398 * memory usage and detecting low memory condition. 399 * 400 * <p> 401 * <b>MBeanServer access</b>:<br> 402 * The mapped type of {@code MemoryUsage} is 403 * {@code CompositeData} with attributes as specified in 404 * {@link MemoryUsage#from MemoryUsage}. 405 * 406 * @return a {@link MemoryUsage} object; or {@code null} if 407 * this pool not valid. 408 */ 409 public MemoryUsage getUsage(); 410 411 /** 412 * Returns the peak memory usage of this memory pool since the 413 * Java virtual machine was started or since the peak was reset. 414 * This method returns {@code null} 415 * if this memory pool is not valid (i.e. no longer exists). 416 * 417 * <p> 418 * <b>MBeanServer access</b>:<br> 419 * The mapped type of {@code MemoryUsage} is 420 * {@code CompositeData} with attributes as specified in 421 * {@link MemoryUsage#from MemoryUsage}. 422 * 423 * @return a {@link MemoryUsage} object representing the peak 424 * memory usage; or {@code null} if this pool is not valid. 425 * 426 */ 427 public MemoryUsage getPeakUsage(); 428 429 /** 430 * Resets the peak memory usage statistic of this memory pool 431 * to the current memory usage. 432 * 433 * @throws java.lang.SecurityException if a security manager 434 * exists and the caller does not have 435 * ManagementPermission("control"). 436 */ 437 public void resetPeakUsage(); 438 439 /** 440 * Tests if this memory pool is valid in the Java virtual 441 * machine. A memory pool becomes invalid once the Java virtual 442 * machine removes it from the memory system. 443 * 444 * @return {@code true} if the memory pool is valid in the running 445 * Java virtual machine; 446 * {@code false} otherwise. 447 */ 448 public boolean isValid(); 449 450 /** 451 * Returns the name of memory managers that manages this memory pool. 452 * Each memory pool will be managed by at least one memory manager. 453 * 454 * @return an array of {@code String} objects, each is the name of 455 * a memory manager managing this memory pool. 456 */ 457 public String[] getMemoryManagerNames(); 458 459 /** 460 * Returns the usage threshold value of this memory pool in bytes. 461 * Each memory pool has a platform-dependent default threshold value. 462 * The current usage threshold can be changed via the 463 * {@link #setUsageThreshold setUsageThreshold} method. 464 * 465 * @return the usage threshold value of this memory pool in bytes. 466 * 467 * @throws UnsupportedOperationException if this memory pool 468 * does not support a usage threshold. 469 * 470 * @see #isUsageThresholdSupported 471 */ 472 public long getUsageThreshold(); 473 474 /** 475 * Sets the threshold of this memory pool to the given {@code threshold} 476 * value if this memory pool supports the usage threshold. 477 * The usage threshold crossing checking is enabled in this memory pool 478 * if the threshold is set to a positive value. 479 * The usage threshold crossing checking is disabled 480 * if it is set to zero. 481 * 482 * @param threshold the new threshold value in bytes. Must be non-negative. 483 * 484 * @throws IllegalArgumentException if {@code threshold} is negative 485 * or greater than the maximum amount of memory for 486 * this memory pool if defined. 487 * 488 * @throws UnsupportedOperationException if this memory pool 489 * does not support a usage threshold. 490 * 491 * @throws java.lang.SecurityException if a security manager 492 * exists and the caller does not have 493 * ManagementPermission("control"). 494 * 495 * @see #isUsageThresholdSupported 496 * @see <a href="#UsageThreshold">Usage threshold</a> 497 */ 498 public void setUsageThreshold(long threshold); 499 500 /** 501 * Tests if the memory usage of this memory pool 502 * reaches or exceeds its usage threshold value. 503 * 504 * @return {@code true} if the memory usage of 505 * this memory pool reaches or exceeds the threshold value; 506 * {@code false} otherwise. 507 * 508 * @throws UnsupportedOperationException if this memory pool 509 * does not support a usage threshold. 510 */ 511 public boolean isUsageThresholdExceeded(); 512 513 /** 514 * Returns the number of times that the memory usage has crossed 515 * the usage threshold. 516 * 517 * @return the number of times that the memory usage 518 * has crossed its usage threshold value. 519 * 520 * @throws UnsupportedOperationException if this memory pool 521 * does not support a usage threshold. 522 */ 523 public long getUsageThresholdCount(); 524 525 /** 526 * Tests if this memory pool supports usage threshold. 527 * 528 * @return {@code true} if this memory pool supports usage threshold; 529 * {@code false} otherwise. 530 */ 531 public boolean isUsageThresholdSupported(); 532 533 /** 534 * Returns the collection usage threshold value of this memory pool 535 * in bytes. The default value is zero. The collection usage 536 * threshold can be changed via the 537 * {@link #setCollectionUsageThreshold setCollectionUsageThreshold} method. 538 * 539 * @return the collection usage threshold of this memory pool in bytes. 540 * 541 * @throws UnsupportedOperationException if this memory pool 542 * does not support a collection usage threshold. 543 * 544 * @see #isCollectionUsageThresholdSupported 545 */ 546 public long getCollectionUsageThreshold(); 547 548 /** 549 * Sets the collection usage threshold of this memory pool to 550 * the given {@code threshold} value. 551 * When this threshold is set to positive, the Java virtual machine 552 * will check the memory usage at its best appropriate time after it has 553 * expended effort in recycling unused objects in this memory pool. 554 * <p> 555 * The collection usage threshold crossing checking is enabled 556 * in this memory pool if the threshold is set to a positive value. 557 * The collection usage threshold crossing checking is disabled 558 * if it is set to zero. 559 * 560 * @param threshold the new collection usage threshold value in bytes. 561 * Must be non-negative. 562 * 563 * @throws IllegalArgumentException if {@code threshold} is negative 564 * or greater than the maximum amount of memory for 565 * this memory pool if defined. 566 * 567 * @throws UnsupportedOperationException if this memory pool 568 * does not support a collection usage threshold. 569 * 570 * @throws java.lang.SecurityException if a security manager 571 * exists and the caller does not have 572 * ManagementPermission("control"). 573 * 574 * @see #isCollectionUsageThresholdSupported 575 * @see <a href="#CollectionThreshold">Collection usage threshold</a> 576 */ 577 public void setCollectionUsageThreshold(long threshold); 578 579 /** 580 * Tests if the memory usage of this memory pool after 581 * the most recent collection on which the Java virtual 582 * machine has expended effort has reached or 583 * exceeded its collection usage threshold. 584 * This method does not request the Java virtual 585 * machine to perform any garbage collection other than its normal 586 * automatic memory management. 587 * 588 * @return {@code true} if the memory usage of this memory pool 589 * reaches or exceeds the collection usage threshold value 590 * in the most recent collection; 591 * {@code false} otherwise. 592 * 593 * @throws UnsupportedOperationException if this memory pool 594 * does not support a usage threshold. 595 */ 596 public boolean isCollectionUsageThresholdExceeded(); 597 598 /** 599 * Returns the number of times that the Java virtual machine 600 * has detected that the memory usage has reached or 601 * exceeded the collection usage threshold. 602 * 603 * @return the number of times that the memory 604 * usage has reached or exceeded the collection usage threshold. 605 * 606 * @throws UnsupportedOperationException if this memory pool 607 * does not support a collection usage threshold. 608 * 609 * @see #isCollectionUsageThresholdSupported 610 */ 611 public long getCollectionUsageThresholdCount(); 612 613 /** 614 * Returns the memory usage after the Java virtual machine 615 * most recently expended effort in recycling unused objects 616 * in this memory pool. 617 * This method does not request the Java virtual 618 * machine to perform any garbage collection other than its normal 619 * automatic memory management. 620 * This method returns {@code null} if the Java virtual 621 * machine does not support this method. 622 * 623 * <p> 624 * <b>MBeanServer access</b>:<br> 625 * The mapped type of {@code MemoryUsage} is 626 * {@code CompositeData} with attributes as specified in 627 * {@link MemoryUsage#from MemoryUsage}. 628 * 629 * @return a {@link MemoryUsage} representing the memory usage of 630 * this memory pool after the Java virtual machine most recently 631 * expended effort in recycling unused objects; 632 * {@code null} if this method is not supported. 633 */ 634 public MemoryUsage getCollectionUsage(); 635 636 /** 637 * Tests if this memory pool supports a collection usage threshold. 638 * 639 * @return {@code true} if this memory pool supports the 640 * collection usage threshold; {@code false} otherwise. 641 */ 642 public boolean isCollectionUsageThresholdSupported(); 643 } |