<api name="J2EEProfilerAPI" type="export" category="friend" group="java">

	J2EE Profiler api/spi is an intergation bridge between J2EE servers registered in IDE 

	and pluggable profiling capability .

</api>

<usecase id="j2ee-profiler-api" name="J2EE Profiler Plugin">

	J2EE application profiling capability could be integrated in to IDE.

	In order to do this plugin needs to implement interface <a href="@TOP@/org/netbeans/modules/j2ee/deployment/profiler/spi/ProfilerProvider.html">

	ProfilerProvider</a> and register it as ProfilerProvider service in default lookup.

	It is important to note that J2EE profiler plugin doesn't provide profiling functionality.

	This plugin just manage J2EE server registered in IDE for profiling purpose.

	It allows to start/stop J2EE server instance and tracks its state.

	There are should be also functionality which allows to <b>profile</b>. But this is not covered here.

	This functionality is separate module.

</usacese>

<usecase id="profiler-distinguish" name="J2EE Profiler Plugin Identifier">

	IDE could have several Profiler providers registered. In order to distinguish them based on some id there is a ProfilerProvider method 

	<code>isApplicable()</code>.  As already was mentioned <b>profiling</b> is functionality of different module. This module

	should be host profiling module with some unique identifier which distinguish it among other plugins.

	Using <code>isApplicable()</code> method one can identify J2EE profiler plugin as related to host profiling module.

</usacese>

<usecase id="profiler-start" name="Start J2EE server in profiling mode">

	There are two ways to start J2EE server in profiling mode:

	<ul>

		<li>Ant task <code>nbstartprofiledserver</code> </li>

		<li>"Start in Profile Mode" action for J2EE server instance ( currently this is AWT Action)</li>

	</ul>

	The first one uses ant task properties configured based on project. 

	<a href="@TOP@/org/netbeans/modules/j2ee/deployment/profiler/api/ProfilerServerSettings.html">ProfilerServerSettings</a> class is instantiated 

	based on this properties . 

	Method "getDefaultServerSettings()" is used in case of starting J2EE server in profile mode without original project properties 

	( case when server is started via AWT Action ).

	<a href="@TOP@/org/netbeans/modules/j2ee/deployment/profiler/spi/ProfilerSession.html">ProfilerSession</a> created by

	<a href="@TOP@/org/netbeans/modules/j2ee/deployment/profiler/spi/ProfilerProvider.html">ProfilerProvider</a>  is used for managing

	profiling of J2EE server instance.

	Profiler provider could support singleton/several simultaneous sessions . In order to handle this situation there is a method

	<code>canConfigure()</code>. User will be asked to stop profiling sessions in case of requested session can't be configured 

	to start till <code>canConfigure</code> return <code>true</code>.

	New session start could require to modify java arguments in 

	<a href="@TOP@/org/netbeans/modules/j2ee/deployment/profiler/api/ProfilerServerSettings.html">ProfilerServerSettings</a> 

	( f.e. network port change , etc. ). This can be done via method <code>configureSession()</code>.

	When session is configured for starting class <a href="@TOP@/org/netbeans/modules/j2ee/deployment/plugins/spi/StartServer">StartServer</a>

	is used for starting J2EE server in profiling mode. Each J2EE server plugin is responsible for implementing 

	profiling functionality implementing.

</usacese>

<usecase id="state-tracking" name="J2EE server state tracking">

	There is a need to track state of J2EE server instance .

	In order to do this <a href="@TOP@/org/netbeans/modules/j2ee/deployment/profiler/spi/ProfilerSession.html">ProfilerSession</a> has

	ability to register listeners.

</usacese>

<usecase id="stop-profiling" name="J2EE server stop">

	There are two ways to stop profiling J2EE server:

	<ul>

		<li>"Stop" action for J2EE server ( currently AWT Action )</li>

		<li>Stop profling with stop profiled application option ( currently this is Stop Profile Button )</code>

	</ul>

	The first one is controlled by J2EE server instance class which has a knowledge about profiling session . There is a session method

	<code>requestStop()</code>. Implementation of this method is responsible for notifying listeners with <code>STATE_STOPPING</code>

	profiling state change. Also it can provide some additional clean up code for profiling stop.

	Other way to stop : Profiler stop with profiled application option .  In this case ProfilerSession implelentation should notify 

	its listeners about state change.

	So in both cases ProfilerSession listeners will be notified by <code>STATE_STOPPING</code> state .

	J2EE server instance class is registered as ProfilerSession listener . So it is able to stop server carefully .

</usacese>