IRuntime.java revision 94f9d3a76184ffc3b163fd4830fcd0fcd80b849f 
1/*******************************************************************************
2 * Copyright (c) 2009, 2010 Mountainminds GmbH & Co. KG and Contributors
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 *    Marc R. Hoffmann - initial API and implementation
10 *
11 * $Id: $
12 *******************************************************************************/
13package org.jacoco.core.runtime;
14
15import org.jacoco.core.data.IExecutionDataVisitor;
16import org.jacoco.core.data.ISessionInfoVisitor;
17
18/**
19 * This interface represents a particular mechanism to collect execution
20 * information in the target VM at runtime.
21 *
22 * @author Marc R. Hoffmann
23 * @version $Revision: $
24 */
25public interface IRuntime extends IExecutionDataAccessorGenerator {
26
27	/**
28	 * Sets a session identifier for this runtime. The identifier is used when
29	 * execution data is collected. If no identifier is explicitly set a
30	 * identifier is generated from the host name and a random number. This
31	 * method can be called at any time.
32	 *
33	 * @see #collect(IExecutionDataVisitor, ISessionInfoVisitor, boolean)
34	 * @param id
35	 *            new session identifier
36	 */
37	public void setSessionId(String id);
38
39	/**
40	 * Get the current a session identifier for this runtime.
41	 *
42	 * @see #setSessionId(String)
43	 * @return current session identifier
44	 */
45	public String getSessionId();
46
47	/**
48	 * Starts the coverage runtime. This method MUST be called before any class
49	 * instrumented for this runtime is loaded.
50	 *
51	 * @throws Exception
52	 *             any internal problem during startup
53	 */
54	public void startup() throws Exception;
55
56	/**
57	 * Allows the coverage runtime to cleanup internals. This class should be
58	 * called when classes instrumented for this runtime are not used any more.
59	 */
60	public void shutdown();
61
62	/**
63	 * Collects the current execution data and writes it to the given
64	 * {@link IExecutionDataVisitor} object. This method must only be called
65	 * between {@link #startup()} and {@link #shutdown()}.
66	 *
67	 * @param executionDataVisitor
68	 *            handler to write coverage data to
69	 * @param sessionInfoVisitor
70	 *            optional visitor to write session information to or
71	 *            <code>null</code> if session information is not required
72	 * @param reset
73	 *            if <code>true</code> the current coverage information is also
74	 *            cleared
75	 */
76	public void collect(IExecutionDataVisitor executionDataVisitor,
77			ISessionInfoVisitor sessionInfoVisitor, boolean reset);
78
79	/**
80	 * Resets all coverage information. This method must only be called between
81	 * {@link #startup()} and {@link #shutdown()}.
82	 */
83	public void reset();
84
85}
86