Included a new MXBean to dynamically configure dump options

jcl/src/java.base/share/classes/com/ibm/oti/util/ExternalMessages-MasterIndex.properties

@@ -1159,6 +1159,7 @@ K05FF="Collection usage threshold cannot exceed maximum amount of memory for poo
 K0660="Internal error while obtaining private constructor."
 K0661="Internal error while obtaining GcInfo instance."
 K0662="maxDepth must not be negative."
+K0663="Invalid or unsupported dump agent option, cannot be triggered."
 
 #java.lang.management
 K0600="className cannot be null"

jcl/src/java.management/share/classes/com/ibm/java/lang/management/internal/ManagementUtils.java

@@ -1,6 +1,6 @@
 /*[INCLUDE-IF Sidecar17]*/
 /*******************************************************************************
- * Copyright (c) 2008, 2017 IBM Corp. and others
+ * Copyright (c) 2008, 2018 IBM Corp. and others
  *
  * This program and the accompanying materials are made available under
  * the terms of the Eclipse Public License 2.0 which accompanies this
@@ -804,6 +804,7 @@ private static final class Component<T extends PlatformManagedObject> {
 		private static final String HYPERVISOR_MXBEAN_NAME = "com.ibm.virtualization.management:type=Hypervisor"; //$NON-NLS-1$
 
 		private static final String JVM_CPU_MONITOR_MXBEAN_NAME = "com.ibm.lang.management:type=JvmCpuMonitor"; //$NON-NLS-1$
+		private static final String OPENJ9_DIAGNOSTICS_MXBEAN_NAME = "openj9.lang.management:type=OpenJ9Diagnostics"; //$NON-NLS-1$
 
 		static void registerAll() {
 			// register standard singleton beans
@@ -839,7 +840,7 @@ static void registerAll() {
 				.addInterface(java.lang.management.ThreadMXBean.class)
 				.validateAndRegister();
 
-			// register IBM-specific singleton beans
+			// register OpenJ9-specific singleton beans
 			create(GUEST_OPERATING_SYSTEM_MXBEAN_NAME, com.ibm.virtualization.management.internal.GuestOS.getInstance())
 				.addInterface(com.ibm.virtualization.management.GuestOSMXBean.class)
 				.validateAndRegister();
@@ -852,6 +853,10 @@ static void registerAll() {
 				.addInterface(com.ibm.lang.management.JvmCpuMonitorMXBean.class)
 				.validateAndRegister();
 
+			create(OPENJ9_DIAGNOSTICS_MXBEAN_NAME, openj9.lang.management.internal.OpenJ9DiagnosticsMXBeanImpl.getInstance())
+				.addInterface(openj9.lang.management.OpenJ9DiagnosticsMXBean.class)
+				.validateAndRegister();
+
 			// register standard optional beans
 			create(ManagementFactory.COMPILATION_MXBEAN_NAME, CompilationMXBeanImpl.getInstance())
 				.addInterface(java.lang.management.CompilationMXBean.class)

jcl/src/jdk.management/share/classes/com/ibm/lang/management/internal/PlatformMBeanProvider.java

@@ -1,6 +1,6 @@
 /*[INCLUDE-IF Sidecar19-SE]*/
 /*******************************************************************************
- * Copyright (c) 2016, 2017 IBM Corp. and others
+ * Copyright (c) 2016, 2018 IBM Corp. and others
  *
  * This program and the accompanying materials are made available under
  * the terms of the Eclipse Public License 2.0 which accompanies this
@@ -22,6 +22,11 @@
  *******************************************************************************/
 package com.ibm.lang.management.internal;
 
+/*[IF Sidecar19-SE-OpenJ9]*/
+import java.lang.ModuleLayer;
+/*[ELSE]
+import java.lang.reflect.Layer;
+/*[ENDIF]*/
 import java.lang.management.ManagementFactory;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -32,9 +37,11 @@
 import com.ibm.lang.management.JvmCpuMonitorMXBean;
 import com.ibm.virtualization.management.internal.GuestOS;
 import com.ibm.virtualization.management.internal.HypervisorMXBeanImpl;
+import openj9.lang.management.OpenJ9DiagnosticsMXBean;
+import openj9.lang.management.internal.OpenJ9DiagnosticsMXBeanImpl;
 
 /**
- * This class implements the service-provider interface to make IBM-specific
+ * This class implements the service-provider interface to make OpenJ9-specific
  * MXBeans available. These beans are either in addition to the basic set or
  * implement non-standard interfaces.
  */
@@ -53,7 +60,7 @@ public final class PlatformMBeanProvider extends sun.management.spi.PlatformMBea
 		 *     PlatformLoggingMXBean
 		 */
 
-		// register IBM extensions of standard singleton beans
+		// register OpenJ9 extensions of standard singleton beans
 		ComponentBuilder.create(ExtendedMemoryMXBeanImpl.getInstance())
 			.addInterface(com.ibm.lang.management.MemoryMXBean.class)
 			.addInterface(java.lang.management.MemoryMXBean.class)
@@ -77,7 +84,7 @@ public final class PlatformMBeanProvider extends sun.management.spi.PlatformMBea
 			.addInterface(java.lang.management.ThreadMXBean.class)
 			.register(allComponents);
 
-		// register IBM-specific singleton beans
+		// register OpenJ9-specific singleton beans
 		ComponentBuilder.create(GuestOS.getInstance())
 			.addInterface(com.ibm.virtualization.management.GuestOSMXBean.class)
 			.register(allComponents);
@@ -90,6 +97,19 @@ public final class PlatformMBeanProvider extends sun.management.spi.PlatformMBea
 			.addInterface(JvmCpuMonitorMXBean.class)
 			.register(allComponents);
 
+		/* OpenJ9DiagnosticsMXBeanImpl depends on openj9.jvm. If openj9.jvm is not
+		 * available exclude this component.
+		 */
+/*[IF Sidecar19-SE-OpenJ9]*/
+		if (ModuleLayer.boot().findModule("openj9.jvm").isPresent()) { //$NON-NLS-1$
+/*[ELSE]
+		if (Layer.boot().findModule("openj9.jvm").isPresent()) { //$NON-NLS-1$
+/*[ENDIF]*/
+			ComponentBuilder.create(OpenJ9DiagnosticsMXBeanImpl.getInstance())
+				.addInterface(OpenJ9DiagnosticsMXBean.class)
+				.register(allComponents);
+		}
+
 		// register beans with zero or more instances
 		ComponentBuilder.create(ManagementFactory.GARBAGE_COLLECTOR_MXBEAN_DOMAIN_TYPE, ExtendedMemoryMXBeanImpl.getInstance().getGarbageCollectorMXBeans())
 			.addInterfaceIf(com.ibm.lang.management.GarbageCollectorMXBean.class, true)

jcl/src/jdk.management/share/classes/module-info.java.extra

@@ -1,6 +1,6 @@
 /*[INCLUDE-IF Sidecar19-SE]*/
 /*******************************************************************************
- * Copyright (c) 2016, 2017 IBM Corp. and others
+ * Copyright (c) 2016, 2018 IBM Corp. and others
  *
  * This program and the accompanying materials are made available under
  * the terms of the Eclipse Public License 2.0 which accompanies this
@@ -22,6 +22,7 @@
  *******************************************************************************/
 module jdk.management {
 	exports com.ibm.lang.management;
+	exports openj9.lang.management;
 	exports com.ibm.virtualization.management;
 	provides sun.management.spi.PlatformMBeanProvider with com.ibm.lang.management.internal.PlatformMBeanProvider;
 }

jcl/src/jdk.management/share/classes/openj9/lang/management/ConfigurationUnavailableException.java

@@ -0,0 +1,41 @@
+/*[INCLUDE-IF Sidecar17]*/
+/*******************************************************************************
+ * Copyright (c) 2018, 2018 IBM Corp. and others
+ *
+ * This program and the accompanying materials are made available under
+ * the terms of the Eclipse Public License 2.0 which accompanies this
+ * distribution and is available at https://www.eclipse.org/legal/epl-2.0/
+ * or the Apache License, Version 2.0 which accompanies this distribution and
+ * is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * This Source Code may also be made available under the following
+ * Secondary Licenses when the conditions for such availability set
+ * forth in the Eclipse Public License, v. 2.0 are satisfied: GNU
+ * General Public License, version 2 with the GNU Classpath
+ * Exception [1] and GNU General Public License, version 2 with the
+ * OpenJDK Assembly Exception [2].
+ *
+ * [1] https://www.gnu.org/software/classpath/license.html
+ * [2] http://openjdk.java.net/legal/assembly-exception.html
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
+ *******************************************************************************/
+
+package openj9.lang.management;
+
+/**
+ * This exception is thrown when the dump configuration cannot be
+ * updated through the methods in OpenJ9DiagnosticMXBean because it is
+ * in use. This is usually because a dump is in progress and the
+ * configuration is locked. A dump may take some time to complete
+ * so this exception is thrown instead of blocking the calling
+ * thread indefinitely.
+ */
+
+public class ConfigurationUnavailableException extends Exception {
+	private static final long serialVersionUID = -7269229433331610188L;
+
+	public ConfigurationUnavailableException(String message, Throwable cause) {
+		super(message, cause);
+	}	
+}

jcl/src/jdk.management/share/classes/openj9/lang/management/InvalidOptionException.java

@@ -0,0 +1,37 @@
+/*[INCLUDE-IF Sidecar17]*/
+/*******************************************************************************
+ * Copyright (c) 2018, 2018 IBM Corp. and others
+ *
+ * This program and the accompanying materials are made available under
+ * the terms of the Eclipse Public License 2.0 which accompanies this
+ * distribution and is available at https://www.eclipse.org/legal/epl-2.0/
+ * or the Apache License, Version 2.0 which accompanies this distribution and
+ * is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * This Source Code may also be made available under the following
+ * Secondary Licenses when the conditions for such availability set
+ * forth in the Eclipse Public License, v. 2.0 are satisfied: GNU
+ * General Public License, version 2 with the GNU Classpath
+ * Exception [1] and GNU General Public License, version 2 with the
+ * OpenJDK Assembly Exception [2].
+ *
+ * [1] https://www.gnu.org/software/classpath/license.html
+ * [2] http://openjdk.java.net/legal/assembly-exception.html
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
+ *******************************************************************************/
+
+package openj9.lang.management;
+
+/**
+ * This exception is thrown when an invalid option is passed
+ * to methods on the openj9.lang.management.OpenJ9DiagnosticsMXBean class.
+ */
+
+public class InvalidOptionException extends Exception {
+	private static final long serialVersionUID = 556407149641748909L;
+
+	public InvalidOptionException(String message, Throwable cause) {
+		super(message, cause);
+	}	
+}

jcl/src/jdk.management/share/classes/openj9/lang/management/OpenJ9DiagnosticsMXBean.java

@@ -0,0 +1,145 @@
+/*[INCLUDE-IF Sidecar17]*/
+/*******************************************************************************
+ * Copyright (c) 2018, 2018 IBM Corp. and others
+ *
+ * This program and the accompanying materials are made available under
+ * the terms of the Eclipse Public License 2.0 which accompanies this
+ * distribution and is available at https://www.eclipse.org/legal/epl-2.0/
+ * or the Apache License, Version 2.0 which accompanies this distribution and
+ * is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * This Source Code may also be made available under the following
+ * Secondary Licenses when the conditions for such availability set
+ * forth in the Eclipse Public License, v. 2.0 are satisfied: GNU
+ * General Public License, version 2 with the GNU Classpath
+ * Exception [1] and GNU General Public License, version 2 with the
+ * OpenJDK Assembly Exception [2].
+ *
+ * [1] https://www.gnu.org/software/classpath/license.html
+ * [2] http://openjdk.java.net/legal/assembly-exception.html
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
+ *******************************************************************************/
+
+
+package openj9.lang.management;
+
+import java.lang.management.PlatformManagedObject;
+
+/**
+ * <p>
+ * This interface provides APIs to dynamically trigger dump agents. APIs are also available to
+ * configure dump options.
+ * This MXBean reuses the methods in com.ibm.jvm.Dump API 
+ * <br>
+ * <table border="1">
+ * <caption><b>Usage example for the {@link OpenJ9DiagnosticsMXBean}</b></caption>
+ * <tr> <td>
+ * <pre>
+ * {@code
+ *   ...
+ *   try {
+ *      mxbeanName = new ObjectName("openj9.lang.management:type=OpenJ9Diagnostics");
+ *   } catch (MalformedObjectNameException e) {
+ *      // Exception Handling
+ *   }
+ *   try {
+ *      MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();
+ *      if (false == mbeanServer.isRegistered(mxbeanName)) {
+ *         // OpenJ9DiagnosticsMXBean not registered
+ *      }
+ *      OpenJ9DiagnosticsMXBean diagBean = JMX.newMXBeanProxy(mbeanServer, mxbeanName, OpenJ9DiagnosticsMXBean.class);
+ *   } catch (Exception e) {
+ *      // Exception Handling
+ *   }
+ * }
+ * </pre></td></tr>
+ * </table>
+ */
+public interface OpenJ9DiagnosticsMXBean extends PlatformManagedObject {
+	/**
+	 * Reset the JVM dump options to the settings specified when the JVM was started removing any additional
+	 * configuration done since then. This method may throw a ConfigurationUnavailableException if the dump 
+	 * configuration cannot be altered. If this occurs it will usually be because a dump event is currently being 
+	 * handled.
+	 *
+	 * @throws ConfigurationUnavailableException if the configuration cannot be changed because a dump is already in progress
+	 * @throws SecurityException if there is a security manager and it doesn't allow the checks required to change the dump settings
+	 */
+	public void resetDumpOptions() throws ConfigurationUnavailableException;
+
+	/**
+	 * This function sets options for the dump subsystem.
+	 * The dump option is passed in as a String. Use the same syntax as the -Xdump command-line option, with the 
+	 * initial -Xdump: omitted. See Using the -Xdump option as described in the section on dump agents in the 
+	 * documentation for the OpenJ9 JVM. This method may throw a ConfigurationUnavailableException if the dump
+	 * configuration cannot be altered.
+	 *
+	 * @param dumpOptions the options string to be set
+	 * @throws InvalidOptionException if the specified dumpOptions cannot be set or is incorrect
+	 * @throws ConfigurationUnavailableException if the configuration cannot be changed because a dump is already in progress
+	 * @throws SecurityException if there is a security manager and it doesn't allow the checks required to change the dump settings
+	 * @throws NullPointerException if dumpOptions is null
+	 */
+	public void setDumpOptions(String dumpOptions) throws InvalidOptionException, ConfigurationUnavailableException;
+
+	/**
+	 * This function triggers the specified dump agent. Dump agents supported - java, snap, system and heap.
+	 * A java dump is in a human-readable format, and summarizes the state of the JVM.
+	 * The default heap dump format (a phd file) is not human-readable.
+	 * A system dump is a platform-specific file that contains information about the active processes, threads, and
+	 * system memory. System dumps are usually large. 
+	 * The snap dump format is not human-readable and must be processed using the trace formatting tool supplied  with the OpenJ9 JVM.
+	 *
+	 * @param dumpAgent the dump agent to be triggered
+	 * @throws IllegalArgumentException if the specified dump agent is invalid or unsupported by this method
+	 * @throws RuntimeException if the vm does not contain RAS dump support
+	 * @throws SecurityException if there is a security manager and it doesn't allow the checks required to trigger this dump
+	 * @throws NullPointerException if dumpAgent is null
+	 */
+	public void triggerDump(String dumpAgent) throws IllegalArgumentException;
+
+	/**
+	 * This function triggers the specified dump agent. Dump agents supported - java, snap, system and heap.
+	 * The JVM will attempt to write the file to the specified file name. This may
+	 * include replacement tokens as documented in the section on dump agents
+	 * in the documentation for the OpenJ9 JVM.
+	 * 
+	 * A string containing the actual filename written to is returned. This may not
+	 * be the same as the requested filename for several reasons:
+	 * <ul>
+	 * <li>null or the empty string was specified, this will cause the JVM to write the
+	 *  dump to the default location based on the current dump settings and return that
+	 *  path.</li>
+	 * <li>Replacement (%) tokens were specified in the file name. These will have been
+	 *  expanded.</li>
+	 * <li>The full path is returned, if only a filename with no directory was specified
+	 *  the full path with the directory the dump was written to will be returned.</li>
+	 * <li>The JVM couldn't write to the specified location. In this case it will attempt
+	 *  to write the dump to another location, unless -Xdump:nofailover was specified on
+	 *  the command line.</li>
+	 * </ul>
+	 * 
+	 * If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be
+	 * made, if this fails a SecurityException will be thrown.
+	 *
+	 * @return the file name that the dump was actually written to 
+	 * @param dumpAgent the dump agent to be triggered
+	 * @param fileNamePattern the filename to write to, which may be null, empty or include replacement tokens
+	 * @throws InvalidOptionException if the fileNamePattern was invalid
+	 * @throws IllegalArgumentException if the specified dump agent is invalid or unsupported by this method
+	 * @throws SecurityException if there is a security manager and it doesn't allow the checks required to trigger this dump
+	 * @throws NullPointerException if dumpAgent is null
+	 */
+	public String triggerDumpToFile(String dumpAgent, String fileNamePattern) throws IllegalArgumentException, InvalidOptionException;
+
+	/**
+	 * This function triggers the heap dump agent and requests for a heap dump in CLASSIC format.
+	 *
+	 * @return The file name of the dump that was created
+	 * @throws InvalidOptionException if the dump operation fails
+	 * @throws RuntimeException if the JVM does not contain RAS dump support
+	 * @throws SecurityException if there is a security manager and it doesn't allow the checks required to trigger this dump
+	 */
+	public String triggerClassicHeapDump() throws InvalidOptionException;
+}