/*******************************************************************************

 * Copyright (c) 2009 SAP AG.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *    SAP AG - initial API and implementation

 *******************************************************************************/

package org.eclipse.mat.snapshot.acquire;

import java.io.File;

import java.util.List;

import org.eclipse.mat.util.IProgressListener;

/**

 * Provides functionality to acquire a heap dump from a locally running Java process

 * 

 * @author ktsvetkov

 *

 */

public interface IHeapDumpProvider

{

	/**

	 * Returns a list of locally running Java processes from which the heap dump

	 * provider can attempt to acquire a heap dump

	 * 

	 * @return List<VmInfo> the list of processes ({@link VmInfo})

	 */

	public List<VmInfo> getAvailableVMs();

	/**

	 * Acquire a heap dump from a locally running Java process. The

	 * 

	 * @param info

	 *            a descriptor of the Java process which should be dumped

	 * @param preferredLocation

	 *            a preferred filename under which the heap dump should be

	 *            saved. The {@link IHeapDumpProvider} is not obliged to provide

	 *            the heap dump at this location

	 * @param listener

	 *            a progress listener

	 * @return the File under which the successfully generated heap dump is

	 *         saved

	 * @throws Exception

	 */

	public File acquireDump(VmInfo info, File preferredLocation, IProgressListener listener) throws Exception;

}

/*******************************************************************************

 * Copyright (c) 2009 SAP AG.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *    SAP AG - initial API and implementation

 *******************************************************************************/

package org.eclipse.mat.snapshot.acquire;

/**

 * Instances of this class are descriptors of locally running Java processes

 * 

 * @author ktsvetkov

 * 

 */

public final class VmInfo

{

	private int pid;

	private String description;

	private boolean heapDumpEnabled;

	private String proposedFileName;

	private IHeapDumpProvider heapDumpProvider;

	/**

	 * An empty constructor

	 */

	public VmInfo()

	{}

	/**

	 * Constructor with parameters

	 * 

	 * @param pid

	 *            the process ID of the process

	 * @param description

	 *            a free text description of the process, usually the process

	 *            name

	 * @param heapDumpEnabled

	 *            a boolean value indicating if a heap dump from the process can

	 *            be acquired

	 * @param proposedFileName

	 *            a proposal for the file name, under which the heap dump can be

	 *            saved. %pid% can be used as a placeholder for the PID.

	 *            Example: java_pid%pid%.hprof

	 * @param heapDumpProvider

	 *            the {@link IHeapDumpProvider} which can use this VmInfo

	 */

	public VmInfo(int pid, String description, boolean heapDumpEnabled, String proposedFileName, IHeapDumpProvider heapDumpProvider)

	{

		super();

		this.pid = pid;

		this.description = description;

		this.heapDumpEnabled = heapDumpEnabled;

		this.proposedFileName = proposedFileName;

		this.heapDumpProvider = heapDumpProvider;

	}

	public int getPid()

	{

		return pid;

	}

	public void setPid(int pid)

	{

		this.pid = pid;

	}

	public String getDescription()

	{

		return description;

	}

	public void setDescription(String description)

	{

		this.description = description;

	}

	public boolean isHeapDumpEnabled()

	{

		return heapDumpEnabled;

	}

	public void setHeapDumpEnabled(boolean heapDumpEnabled)

	{

		this.heapDumpEnabled = heapDumpEnabled;

	}

	public IHeapDumpProvider getHeapDumpProvider()

	{

		return heapDumpProvider;

	}

	public void setHeapDumpProvider(IHeapDumpProvider heapDumpProvider)

	{

		this.heapDumpProvider = heapDumpProvider;

	}

	public String getProposedFileName()

	{

		return proposedFileName;

	}

	public void setProposedFileName(String proposedFileName)

	{

		this.proposedFileName = proposedFileName;

	}

	@Override

	public String toString()

	{

		return "PID = " + pid + "\t" + description;

	}

}

<?xml version='1.0' encoding='UTF-8'?>

<!-- Schema file written by PDE -->

<schema targetNamespace="org.eclipse.mat.api" xmlns="http://www.w3.org/2001/XMLSchema">

<annotation>

      <appInfo>

         <meta.schema plugin="org.eclipse.mat.api" id="heapDumpProvider" name="Heap Dump Provider"/>

      </appInfo>

      <documentation>

         [Enter description of this extension point.]

      </documentation>

   </annotation>

   <element name="extension">

      <annotation>

         <appInfo>

            <meta.element />

         </appInfo>

      </annotation>

      <complexType>

         <sequence minOccurs="0" maxOccurs="unbounded">

            <element ref="provider"/>

         </sequence>

         <attribute name="point" type="string" use="required">

            <annotation>

               <documentation>

               </documentation>

            </annotation>

         </attribute>

         <attribute name="id" type="string">

            <annotation>

               <documentation>

               </documentation>

            </annotation>

         </attribute>

         <attribute name="name" type="string">

            <annotation>

               <documentation>

               </documentation>

               <appInfo>

                  <meta.attribute translatable="true"/>

               </appInfo>

            </annotation>

         </attribute>

      </complexType>

   </element>

   <element name="provider">

      <complexType>

         <attribute name="impl" type="string">

            <annotation>

               <documentation>

               </documentation>

               <appInfo>

                  <meta.attribute kind="java" basedOn=":org.eclipse.mat.snapshot.acquire.IHeapDumpProvider"/>

               </appInfo>

            </annotation>

         </attribute>

      </complexType>

   </element>

   <annotation>

      <appInfo>

         <meta.section type="since"/>

      </appInfo>

      <documentation>

         [Enter the first release in which this extension point appears.]

      </documentation>

   </annotation>

   <annotation>

      <appInfo>

         <meta.section type="examples"/>

      </appInfo>

      <documentation>

         [Enter extension point usage example here.]

      </documentation>

   </annotation>

   <annotation>

      <appInfo>

         <meta.section type="apiinfo"/>

      </appInfo>

      <documentation>

         [Enter API information here.]

      </documentation>

   </annotation>

   <annotation>

      <appInfo>

         <meta.section type="implementation"/>

      </appInfo>

      <documentation>

         [Enter information about supplied implementation of this extension point.]

      </documentation>

   </annotation>

</schema>

 <extension-point id="heapDumpProvider" name="Heap Dump Provider" schema="schema/heapDumpProvider.exsd"/>