Blame - ipojo/handler/jmx/doc/ipojo-jmx-handler.html - onos-felix

<LI><SPAN class="nobr"><A href="downloads.html" title="Visit page outside Confluence" rel="nofollow">downloads<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>

23

<LI><A href="documentation.html" title="documentation">documentation</A></LI>

24

<LI><A href="mailinglists.html" title="mailinglists">mailing lists</A></LI>

25

<LI><A href="contributing.html" title="Contributing">contributing</A></LI>

26

27

<LI><SPAN class="nobr"><A href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>

28

<LI><SPAN class="nobr"><A href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>

29

30

31

32

</LI>

</UL>

</DIV>

<H1><A name="iPOJOJMXHandler-iPOJOJMXHandler"></A>iPOJO JMX Handler</H1>

40

41

<P>This handler provides JMX management of component instance. It could be useful to manage instance remotely. As the handler exposes MBeans, you must have a MBean server running on your platform (as the platform MBean server or the MOSGi MBean Server).</P>

42

43

<H2><A name="iPOJOJMXHandler-Features"></A>Features</H2>

44

45

<P>The handler allows to:</P>

46

<UL>

47

<LI>Expose attributes accessible via JMX (with rights management).</LI>

48

<LI>Expose methods to be called through JMX.</LI>

49

<LI>Get notifications when attributes are modified .</LI>

</UL>

<H2><A name="iPOJOJMXHandler-Prerequisites"></A>Prerequisites</H2>

54

55

<P>To be functional this handler must register on an MBean Server,thus you obviously need it. Several servers are currently supported : the standard platform MBean server (included in the JDK), MOSGi (provided with Felix), ...<BR>

56

To use MOSGi, you have to deploy at least the following three bundles of MOSGi:</P>

57

<UL>

58

<LI>org.apache.felix.mosgi.jmx.agent</LI>

59

<LI>org.apache.felix.mosgi.jmx.registry</LI>

60

<LI>org.apache.felix.mosgi.jmx.rmiconnector</LI>

</UL>

<P>You can find MOSGi documentation on <SPAN class="nobr"><A href="http://cwiki.apache.org/FELIX/mosgi-managed-osgi-framework.html" title="Visit page outside Confluence" rel="nofollow">http://cwiki.apache.org/FELIX/mosgi-managed-osgi-framework.html<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></P>

65

66

<H2><A name="iPOJOJMXHandler-Download"></A>Download</H2>

67

68

<P>The JMX handler is available in the Felix trunk in the iPOJO project. See the <A href="download.html" title="Download">Download</A> page to download and compile these sources.</P>

<P>The handler needs to be added in the metadata.xml, you just add a namespace (e.g., jmx) :</P>

73

74

<PRE class="code-xml"><SPAN class="code-tag"><ipojo <SPAN class="code-keyword">xmlns:jmx</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.jmx"</SPAN>></SPAN>

...

</DIV></DIV>

<P>So, you could now expose in JMX properties and methods of your component. They are surrounded by the <jmx:config><BR>

tag.</P>

<SPAN class="code-tag"><property name=<SPAN class="code-quote">"message"</SPAN> field=<SPAN class="code-quote">"m_msg"</SPAN> rights=<SPAN class="code-quote">"w"</SPAN> notification=<SPAN class="code-quote">"true"</SPAN>/></SPAN>

83

<SPAN class="code-tag"><method name=<SPAN class="code-quote">"doSomethingBad"</SPAN>/></SPAN>

84

<SPAN class="code-tag"><method name=<SPAN class="code-quote">"doSomethingGood"</SPAN>/></SPAN>

85

86

</DIV></DIV>

87

<P><EM>Note:</EM> Be careful that the argument and return type of methods must be serializable. In case of several methods have the same name, each of them will be exposed.</P>

88

89

<H2><A name="iPOJOJMXHandler-JMXHandleroptions"></A>JMX Handler options</H2>

90

91

<P>Here you can find all configuration options of the JMX handler. There are two kinds of manageable elements : properties and methods. First is described the global configuration of the handler. Then elements can be configured, using several attributes, as described below.</P>

92

93

<H2><A name="iPOJOJMXHandler-Globalhandlerattributes"></A>Global handler attributes</H2>

94

95

<TR>

96

<TH class="confluenceTh">Attribute name </TH>

97

<TH class="confluenceTh"> Required </TH>

98

<TH class="confluenceTh"> Description</TH>

99

</TR>

100

<TR>

101

<TD class="confluenceTd">objectName</TD>

102

103

<TD class="confluenceTd">The complete object name of the managed component. The syntax of this attribute must be compliant with the ObjectName syntax, detailed in the JMX specification.<BR>

104

If neither domain nor name attributes are specified, the default value is determined by the package, the type and the instance name of the component. This attribute overrides the domain and name attributes.<BR>

105

<EM>Example:</EM> "my.domain:type=myType,name=myName"</TD>

106

</TR>

107

<TR>

108

<TD class="confluenceTd">domain</TD>

109

110

<TD class="confluenceTd">The domain of the managed object (i.e., the left part of the object name). This attribute must be compliant with the domain syntax, as described in the JMX specification.<BR>

111

<EM>Example:</EM> "my.domain"</TD>

</TR>

<TR>

<TD class="confluenceTd">The name property of the managed object. The value of this attribute must comply with the ObjectName value syntax, as described in the JMX specification.</TD>

117

</TR>

118

<TR>

119

<TD class="confluenceTd">usesMOSGi</TD>

120

121

<TD class="confluenceTd">Determines if the component must be register on the MOSGi MBean server or not.</TD>

122

</TR>

123

<TR>

124

<TD class="confluenceTd">preRegister <BR>

postRegister <BR>

preDeregister<BR>

postDeregister</TD>

<TD class="confluenceTd">These attributes allow to specify methods to carry out operations before and after being registered or unregistered from the MBean server.</TD>

</TR>

</TBODY></TABLE>

<H2><A name="iPOJOJMXHandler-Propertiesattributes"></A>Properties attributes</H2>

134

135

<TR>

136

<TH class="confluenceTh">Attribute name</TH>

137

<TH class="confluenceTh">Required</TH>

138

<TH class="confluenceTh">Description</TH>

139

</TR>

140

<TR>

141

<TD class="confluenceTd">field</TD>

142

143

<TD class="confluenceTd">The name of the component's field to expose.</TD>

</TR>

<TR>

<TD class="confluenceTd">The name of the property as it will appear in JMX. If unspecified, the default value is the name of the exposed field.</TD>

149

</TR>

150

<TR>

151

<TD class="confluenceTd">rights</TD>

152

153

<TD class="confluenceTd">Specify the access permission of the exposed field. The accepted values are :

154

<UL>

155

<LI>"r" : read-only access, the default value.</LI>

156

<LI>"w" : read and write access.</LI>

</UL>

</TD>

</TR>

<TR>

<TD class="confluenceTd">notification</TD>

162

163

<TD class="confluenceTd">Enable or disable attribute change notification sending for this property. If set to "true", a notification is sent each time the value of the field changes.</TD>

</TR>

</TBODY></TABLE>

<H2><A name="iPOJOJMXHandler-Methodsattributes"></A>Methods attributes</H2>

168

169

<TR>

170

<TH class="confluenceTh">Attribute name</TH>

171

<TH class="confluenceTh">Required</TH>

172

<TH class="confluenceTh">Description</TH>

</TR>

<TR>

<TD class="confluenceTd">The name of the method to expose. If multiple methods have the same name, all of them are exposed.</TD>

178

</TR>

179

<TR>

180

<TD class="confluenceTd">description</TD>

181

182

<TD class="confluenceTd">The description of the exposed method, as it will appear in JMX.</TD>

</TR>

</TBODY></TABLE>

<H2><A name="iPOJOJMXHandler-Examples"></A>Examples</H2>

188

189

<P>In this part, we will give you a complete example of a component managed with JMX, using the JConsole provided by the SUN JDK.</P>

190

191

<H3><A name="iPOJOJMXHandler-ExposingAttributes"></A>Exposing Attributes</H3>

192

193

<P>In first time we create a simple component named MyComponent. We have add two fields named m_level (int) and m_message (String).</P>

194

195

<PRE class="code-java"><SPAN class="code-keyword">public</SPAN> class

196

MyComponent ... {

197

<SPAN class="code-comment">// Exposed attributes

198

</SPAN> <SPAN class="code-keyword">private</SPAN> <SPAN class="code-object">String</SPAN> m_message;

199

<SPAN class="code-keyword">private</SPAN> <SPAN class="code-object">int</SPAN> m_level;

200

}</PRE>

201

</DIV></DIV>

202

<P>We expose now the attributes in the jmx:config<BR>

203

tag in the metadata :</P>

204

205

<PRE class="code-xml"><SPAN class="code-tag"><?xml version=<SPAN class="code-quote">"1.0"</SPAN> encoding=<SPAN class="code-quote">"UTF-8"</SPAN>?></SPAN>

206

<SPAN class="code-tag"><iPOJO <SPAN class="code-keyword">xmlns:jmx</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.jmx"</SPAN>></SPAN>

207

<component className=<SPAN class="code-quote">"...MyComponent"</SPAN>

208

architecture=<SPAN class="code-quote">"true"</SPAN>

209

immediate=<SPAN class="code-quote">"true"</SPAN>>

<property field=<SPAN class="code-quote">"m_level"</SPAN>

215

name=<SPAN class="code-quote">"The level"</SPAN>

216

rights=<SPAN class="code-quote">"r"</SPAN>/>

217

<property field=<SPAN class="code-quote">"m_message"</SPAN>

218

name=<SPAN class="code-quote">"The message"</SPAN>

219

rights=<SPAN class="code-quote">"w"</SPAN>/>

<instance

component=<SPAN class="code-quote">"...MyComponent"</SPAN>/>

224

225

</DIV></DIV>

226

<P>Now, we could get and write the properties in the JConsole :<BR>

227

228

229

<H3><A name="iPOJOJMXHandler-ExposingMethods"></A>Exposing Methods</H3>

230

231

<P>We could now add methods in the initial class :</P>

232

233

<PRE class="code-java">/**

234

Do something good

235

*/

236

<SPAN class="code-keyword">public</SPAN> void doSomethingGood() {

...

}

/**

Do something bad

*/

<SPAN class="code-keyword">public</SPAN> void doSomethingBad() {

...

}

/**

Do nothing

*/

<SPAN class="code-keyword">public</SPAN> void doNothing() {

...

}</PRE>

</DIV></DIV>

<P>We add corresponding tags in the metadata to expose these methods:</P>

255

256

257

<method name=<SPAN class="code-quote">"doSomethingGood"</SPAN>

258

description=<SPAN class="code-quote">"Do something good."</SPAN>/>

259

<method name=<SPAN class="code-quote">"doSomethingBad"</SPAN>

260

description=<SPAN class="code-quote">"Do something bad."</SPAN>/>

261

<method name=<SPAN class="code-quote">"doNothing"</SPAN>

262

description=<SPAN class="code-quote">"Do absolutely nothing."</SPAN>/></PRE>

263

</DIV></DIV>

264

<P>Now the three methods are exposed in the operations tab of the JConsole. We can invoked these methods :</P>

<H3><A name="iPOJOJMXHandler-AttributeNotifications%3A"></A>Attribute Notifications:</H3>

269

270

<P>You could subscribe to attribute notification by adding the notification attribute in property tag. In our example if we want to be notified when m_level is modified, we change the property line in the metatada like this:</P>

271

272

<PRE class="code-xml"><property field=<SPAN class="code-quote">"m_level"</SPAN>

273

name=<SPAN class="code-quote">"The level"</SPAN>

274

rights=<SPAN class="code-quote">"r"</SPAN>

275

notification=<SPAN class="code-quote">"true"</SPAN>/></PRE>

276

</DIV></DIV>

277

<P>So now if we change the string through JConsole or if the POJO is modified in other way, a notification will be sent to every listener. For example, we subscribe in the notification tab, and we get notification when the message changes :</P>

</TD>

<H6><A name="iPOJOJMXHandler-Overview"></A><B>Overview</B></H6>

283

<UL>

284

285

<LI><A href="apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</A></LI>

286

<LI><A href="download.html" title="Download">Download & Install </A></LI>

</UL>

<H6><A name="iPOJOJMXHandler-GettingStarted"></A><B>Getting Started</B></H6>

291

<UL>

292

<LI><A href="ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</A></LI>

293

<LI><A href="ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</A></LI>

294

<LI><A href="ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</A></LI>

</UL>

<H6><A name="iPOJOJMXHandler-UserGuide"></A><B>User Guide</B></H6>

299

<UL>

300

<LI><A href="describing-components.html" title="Describing components">Describing components (handler list) </A></LI>

301

<LI><A href="how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</A></LI>

302

<LI><A href="ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</A></LI>

</UL>

<H6><A name="iPOJOJMXHandler-Tools"></A><B>Tools</B></H6>

308

<UL>

309

<LI><A href="ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</A></LI>

310

<LI><A href="ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</A></LI>

311

<LI><A href="ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</A></LI>

312

<LI><A href="ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</A></LI>

</UL>

<H6><A name="iPOJOJMXHandler-DeveloperGuide"></A><B>Developer Guide</B></H6>

317

<UL>

318

319

<LI><A href="how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</A></LI>

320

<LI><A href="how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</A></LI>

</UL>

<H6><A name="iPOJOJMXHandler-Misc%26Contact"></A><B>Misc & Contact</B></H6>

325

<UL>

326

<LI><A href="apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</A></LI>

327

<LI><A href="apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</A></LI>

328

<LI><A href="apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</A></LI>

329

<LI><A href="future-ideas.html" title="Future Ideas">Future Ideas</A></LI>

330

<LI><A href="contact.html" title="Contact">Contact</A></LI>

331

<LI><A href="related-works.html" title="Related Works">Related Works</A></LI>

332

<LI><A href="article-presentations.html" title="Article & Presentations">Article & Presentations</A></LI>

</UL>

<HR>

</DIV>

</BODY>

343

</HTML>

Clement Escoffier	130ca57	2008-10-13 07:33:03 +0000	[diff] [blame]	1
				2	<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
				3	<HTML>
				4
				5	<!-- Mirrored Site: felix.apache.org. File: /site/ipojo-jmx-handler.html. Date: Mon, 13 Oct 2008 06:53:08 GMT -->
				6	<HEAD>
				7	<TITLE>Apache Felix - iPOJO JMX Handler</TITLE>
				8	<LINK rel="stylesheet" href="media.data/site.css" type="text/css" media="all">
				9	<META http-equiv="Content-Type" content="text/html;charset=UTF-8">
				10	</HEAD>
				11	<BODY>
				12	<DIV class="title"><DIV class="logo"><A href="index.html"><IMG border="0" alt="Apache Felix" src="media.data/logo.png"></A></DIV><DIV class="header"><A href="http://www.apache.org/"><IMG border="0" alt="Apache" src="media.data/apache.png"></A></DIV></DIV>
				13	<DIV class="menu">
				14
				15
				16
				17
				18
				19	<UL>
				20	<LI><A href="news.html" title="news">news</A></LI>
				21	<LI><A href="license.html" title="license">license</A></LI>
				22	<LI><SPAN class="nobr"><A href="downloads.html" title="Visit page outside Confluence" rel="nofollow">downloads<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
				23	<LI><A href="documentation.html" title="documentation">documentation</A></LI>
				24	<LI><A href="mailinglists.html" title="mailinglists">mailing lists</A></LI>
				25	<LI><A href="contributing.html" title="Contributing">contributing</A></LI>
				26	<LI><SPAN class="nobr"><A href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
				27	<LI><SPAN class="nobr"><A href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
				28	<LI><SPAN class="nobr"><A href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>
				29	<!-- ApacheCon Ad -->
				30	<IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
				31	<P style="height: 100px">
				32	<!-- ApacheCon Ad --></LI>
				33	</UL>
				34	</DIV>
				35	<DIV class="main">
				36	<TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR>
				37	<TD class="confluenceTd" valign="top" width="80%">
				38
				39	<H1><A name="iPOJOJMXHandler-iPOJOJMXHandler"></A>iPOJO JMX Handler</H1>
				40
				41	<P>This handler provides JMX management of component instance. It could be useful to manage instance remotely. As the handler exposes MBeans, you must have a MBean server running on your platform (as the platform MBean server or the MOSGi MBean Server).</P>
				42
				43	<H2><A name="iPOJOJMXHandler-Features"></A>Features</H2>
				44
				45	<P>The handler allows to:</P>
				46	<UL>
				47	<LI>Expose attributes accessible via JMX (with rights management).</LI>
				48	<LI>Expose methods to be called through JMX.</LI>
				49	<LI>Get notifications when attributes are modified .</LI>
				50	</UL>
				51
				52
				53	<H2><A name="iPOJOJMXHandler-Prerequisites"></A>Prerequisites</H2>
				54
				55	<P>To be functional this handler must register on an MBean Server,thus you obviously need it. Several servers are currently supported : the standard platform MBean server (included in the JDK), MOSGi (provided with Felix), ...<BR>
				56	To use MOSGi, you have to deploy at least the following three bundles of MOSGi:</P>
				57	<UL>
				58	<LI>org.apache.felix.mosgi.jmx.agent</LI>
				59	<LI>org.apache.felix.mosgi.jmx.registry</LI>
				60	<LI>org.apache.felix.mosgi.jmx.rmiconnector</LI>
				61	</UL>
				62
				63
				64	<P>You can find MOSGi documentation on <SPAN class="nobr"><A href="http://cwiki.apache.org/FELIX/mosgi-managed-osgi-framework.html" title="Visit page outside Confluence" rel="nofollow">http://cwiki.apache.org/FELIX/mosgi-managed-osgi-framework.html<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></P>
				65
				66	<H2><A name="iPOJOJMXHandler-Download"></A>Download</H2>
				67
				68	<P>The JMX handler is available in the Felix trunk in the iPOJO project. See the <A href="download.html" title="Download">Download</A> page to download and compile these sources.</P>
				69
				70	<H2><A name="iPOJOJMXHandler-Howtouseit"></A>How to use it</H2>
				71
				72	<P>The handler needs to be added in the metadata.xml, you just add a namespace (e.g., jmx) :</P>
				73	<DIV class="code"><DIV class="codeContent">
				74	<PRE class="code-xml"><SPAN class="code-tag"><ipojo <SPAN class="code-keyword">xmlns:jmx</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.jmx"</SPAN>></SPAN>
				75	...
				76	<SPAN class="code-tag"></ipojo></SPAN></PRE>
				77	</DIV></DIV>
				78	<P>So, you could now expose in JMX properties and methods of your component. They are surrounded by the <jmx:config><BR>
				79	tag.</P>
				80	<DIV class="code"><DIV class="codeContent">
				81	<PRE class="code-xml"><SPAN class="code-tag"><jmx:config></SPAN>
				82	<SPAN class="code-tag"><property name=<SPAN class="code-quote">"message"</SPAN> field=<SPAN class="code-quote">"m_msg"</SPAN> rights=<SPAN class="code-quote">"w"</SPAN> notification=<SPAN class="code-quote">"true"</SPAN>/></SPAN>
				83	<SPAN class="code-tag"><method name=<SPAN class="code-quote">"doSomethingBad"</SPAN>/></SPAN>
				84	<SPAN class="code-tag"><method name=<SPAN class="code-quote">"doSomethingGood"</SPAN>/></SPAN>
				85	<SPAN class="code-tag"></jmx:config></SPAN></PRE>
				86	</DIV></DIV>
				87	<P><EM>Note:</EM> Be careful that the argument and return type of methods must be serializable. In case of several methods have the same name, each of them will be exposed.</P>
				88
				89	<H2><A name="iPOJOJMXHandler-JMXHandleroptions"></A>JMX Handler options</H2>
				90
				91	<P>Here you can find all configuration options of the JMX handler. There are two kinds of manageable elements : properties and methods. First is described the global configuration of the handler. Then elements can be configured, using several attributes, as described below.</P>
				92
				93	<H2><A name="iPOJOJMXHandler-Globalhandlerattributes"></A>Global handler attributes</H2>
				94	<TABLE class="confluenceTable"><TBODY>
				95	<TR>
				96	<TH class="confluenceTh">Attribute name </TH>
				97	<TH class="confluenceTh"> Required </TH>
				98	<TH class="confluenceTh"> Description</TH>
				99	</TR>
				100	<TR>
				101	<TD class="confluenceTd">objectName</TD>
				102	<TD class="confluenceTd">NO</TD>
				103	<TD class="confluenceTd">The complete object name of the managed component. The syntax of this attribute must be compliant with the ObjectName syntax, detailed in the JMX specification.<BR>
				104	If neither domain nor name attributes are specified, the default value is determined by the package, the type and the instance name of the component. This attribute overrides the domain and name attributes.<BR>
				105	<EM>Example:</EM> "my.domain:type=myType,name=myName"</TD>
				106	</TR>
				107	<TR>
				108	<TD class="confluenceTd">domain</TD>
				109	<TD class="confluenceTd">NO</TD>
				110	<TD class="confluenceTd">The domain of the managed object (i.e., the left part of the object name). This attribute must be compliant with the domain syntax, as described in the JMX specification.<BR>
				111	<EM>Example:</EM> "my.domain"</TD>
				112	</TR>
				113	<TR>
				114	<TD class="confluenceTd">name</TD>
				115	<TD class="confluenceTd">NO</TD>
				116	<TD class="confluenceTd">The name property of the managed object. The value of this attribute must comply with the ObjectName value syntax, as described in the JMX specification.</TD>
				117	</TR>
				118	<TR>
				119	<TD class="confluenceTd">usesMOSGi</TD>
				120	<TD class="confluenceTd">NO</TD>
				121	<TD class="confluenceTd">Determines if the component must be register on the MOSGi MBean server or not.</TD>
				122	</TR>
				123	<TR>
				124	<TD class="confluenceTd">preRegister <BR>
				125	postRegister <BR>
				126	preDeregister<BR>
				127	postDeregister</TD>
				128	<TD class="confluenceTd">NO</TD>
				129	<TD class="confluenceTd">These attributes allow to specify methods to carry out operations before and after being registered or unregistered from the MBean server.</TD>
				130	</TR>
				131	</TBODY></TABLE>
				132
				133	<H2><A name="iPOJOJMXHandler-Propertiesattributes"></A>Properties attributes</H2>
				134	<TABLE class="confluenceTable"><TBODY>
				135	<TR>
				136	<TH class="confluenceTh">Attribute name</TH>
				137	<TH class="confluenceTh">Required</TH>
				138	<TH class="confluenceTh">Description</TH>
				139	</TR>
				140	<TR>
				141	<TD class="confluenceTd">field</TD>
				142	<TD class="confluenceTd">YES</TD>
				143	<TD class="confluenceTd">The name of the component's field to expose.</TD>
				144	</TR>
				145	<TR>
				146	<TD class="confluenceTd">name</TD>
				147	<TD class="confluenceTd">NO</TD>
				148	<TD class="confluenceTd">The name of the property as it will appear in JMX. If unspecified, the default value is the name of the exposed field.</TD>
				149	</TR>
				150	<TR>
				151	<TD class="confluenceTd">rights</TD>
				152	<TD class="confluenceTd">NO</TD>
				153	<TD class="confluenceTd">Specify the access permission of the exposed field. The accepted values are :
				154	<UL>
				155	<LI>"r" : read-only access, the default value.</LI>
				156	<LI>"w" : read and write access.</LI>
				157	</UL>
				158	</TD>
				159	</TR>
				160	<TR>
				161	<TD class="confluenceTd">notification</TD>
				162	<TD class="confluenceTd">NO</TD>
				163	<TD class="confluenceTd">Enable or disable attribute change notification sending for this property. If set to "true", a notification is sent each time the value of the field changes.</TD>
				164	</TR>
				165	</TBODY></TABLE>
				166
				167	<H2><A name="iPOJOJMXHandler-Methodsattributes"></A>Methods attributes</H2>
				168	<TABLE class="confluenceTable"><TBODY>
				169	<TR>
				170	<TH class="confluenceTh">Attribute name</TH>
				171	<TH class="confluenceTh">Required</TH>
				172	<TH class="confluenceTh">Description</TH>
				173	</TR>
				174	<TR>
				175	<TD class="confluenceTd">name</TD>
				176	<TD class="confluenceTd">YES</TD>
				177	<TD class="confluenceTd">The name of the method to expose. If multiple methods have the same name, all of them are exposed.</TD>
				178	</TR>
				179	<TR>
				180	<TD class="confluenceTd">description</TD>
				181	<TD class="confluenceTd">NO</TD>
				182	<TD class="confluenceTd">The description of the exposed method, as it will appear in JMX.</TD>
				183	</TR>
				184	</TBODY></TABLE>
				185
				186
				187	<H2><A name="iPOJOJMXHandler-Examples"></A>Examples</H2>
				188
				189	<P>In this part, we will give you a complete example of a component managed with JMX, using the JConsole provided by the SUN JDK.</P>
				190
				191	<H3><A name="iPOJOJMXHandler-ExposingAttributes"></A>Exposing Attributes</H3>
				192
				193	<P>In first time we create a simple component named MyComponent. We have add two fields named m_level (int) and m_message (String).</P>
				194	<DIV class="code"><DIV class="codeContent">
				195	<PRE class="code-java"><SPAN class="code-keyword">public</SPAN> class
				196	MyComponent ... {
				197	<SPAN class="code-comment">// Exposed attributes
				198	</SPAN> <SPAN class="code-keyword">private</SPAN> <SPAN class="code-object">String</SPAN> m_message;
				199	<SPAN class="code-keyword">private</SPAN> <SPAN class="code-object">int</SPAN> m_level;
				200	}</PRE>
				201	</DIV></DIV>
				202	<P>We expose now the attributes in the jmx:config<BR>
				203	tag in the metadata :</P>
				204	<DIV class="code"><DIV class="codeContent">
				205	<PRE class="code-xml"><SPAN class="code-tag"><?xml version=<SPAN class="code-quote">"1.0"</SPAN> encoding=<SPAN class="code-quote">"UTF-8"</SPAN>?></SPAN>
				206	<SPAN class="code-tag"><iPOJO <SPAN class="code-keyword">xmlns:jmx</SPAN>=<SPAN class="code-quote">"org.apache.felix.ipojo.handlers.jmx"</SPAN>></SPAN>
				207	<component className=<SPAN class="code-quote">"...MyComponent"</SPAN>
				208	architecture=<SPAN class="code-quote">"true"</SPAN>
				209	immediate=<SPAN class="code-quote">"true"</SPAN>>
				210
				211	<SPAN class="code-tag"><provides/></SPAN>
				212	<SPAN class="code-tag"><jmx:config></SPAN>
				213	<SPAN class="code-tag"><SPAN class="code-comment"><!-- Exposed properties --></SPAN></SPAN>
				214	<property field=<SPAN class="code-quote">"m_level"</SPAN>
				215	name=<SPAN class="code-quote">"The level"</SPAN>
				216	rights=<SPAN class="code-quote">"r"</SPAN>/>
				217	<property field=<SPAN class="code-quote">"m_message"</SPAN>
				218	name=<SPAN class="code-quote">"The message"</SPAN>
				219	rights=<SPAN class="code-quote">"w"</SPAN>/>
				220	<SPAN class="code-tag"></jmx:config></SPAN>
				221	<SPAN class="code-tag"></component></SPAN>
				222	<instance
				223	component=<SPAN class="code-quote">"...MyComponent"</SPAN>/>
				224	<SPAN class="code-tag"></iPOJO></SPAN></PRE>
				225	</DIV></DIV>
				226	<P>Now, we could get and write the properties in the JConsole :<BR>
				227	<IMG src="ipojo-jmx-handler.data/JMXHandler_1.png" align="absmiddle" border="0"></P>
				228
				229	<H3><A name="iPOJOJMXHandler-ExposingMethods"></A>Exposing Methods</H3>
				230
				231	<P>We could now add methods in the initial class :</P>
				232	<DIV class="code"><DIV class="codeContent">
				233	<PRE class="code-java">/**
				234	Do something good
				235	*/
				236	<SPAN class="code-keyword">public</SPAN> void doSomethingGood() {
				237	...
				238	}
				239
				240	/**
				241	Do something bad
				242	*/
				243	<SPAN class="code-keyword">public</SPAN> void doSomethingBad() {
				244	...
				245	}
				246
				247	/**
				248	Do nothing
				249	*/
				250	<SPAN class="code-keyword">public</SPAN> void doNothing() {
				251	...
				252	}</PRE>
				253	</DIV></DIV>
				254	<P>We add corresponding tags in the metadata to expose these methods:</P>
				255	<DIV class="code"><DIV class="codeContent">
				256	<PRE class="code-xml"><SPAN class="code-tag"><SPAN class="code-comment"><!-- Exposed methods --></SPAN></SPAN>
				257	<method name=<SPAN class="code-quote">"doSomethingGood"</SPAN>
				258	description=<SPAN class="code-quote">"Do something good."</SPAN>/>
				259	<method name=<SPAN class="code-quote">"doSomethingBad"</SPAN>
				260	description=<SPAN class="code-quote">"Do something bad."</SPAN>/>
				261	<method name=<SPAN class="code-quote">"doNothing"</SPAN>
				262	description=<SPAN class="code-quote">"Do absolutely nothing."</SPAN>/></PRE>
				263	</DIV></DIV>
				264	<P>Now the three methods are exposed in the operations tab of the JConsole. We can invoked these methods :</P>
				265
				266	<P><IMG src="ipojo-jmx-handler.data/JMXHandler_2.png" align="absmiddle" border="0"></P>
				267
				268	<H3><A name="iPOJOJMXHandler-AttributeNotifications%3A"></A>Attribute Notifications:</H3>
				269
				270	<P>You could subscribe to attribute notification by adding the notification attribute in property tag. In our example if we want to be notified when m_level is modified, we change the property line in the metatada like this:</P>
				271	<DIV class="code"><DIV class="codeContent">
				272	<PRE class="code-xml"><property field=<SPAN class="code-quote">"m_level"</SPAN>
				273	name=<SPAN class="code-quote">"The level"</SPAN>
				274	rights=<SPAN class="code-quote">"r"</SPAN>
				275	notification=<SPAN class="code-quote">"true"</SPAN>/></PRE>
				276	</DIV></DIV>
				277	<P>So now if we change the string through JConsole or if the POJO is modified in other way, a notification will be sent to every listener. For example, we subscribe in the notification tab, and we get notification when the message changes :</P>
				278
				279	<P><IMG src="ipojo-jmx-handler.data/JMXHandler_3.png" align="absmiddle" border="0"></P>
				280	</TD>
				281	<TD class="confluenceTd" valign="top" width="20%">
				282	<H6><A name="iPOJOJMXHandler-Overview"></A><B>Overview</B></H6>
				283	<UL>
				284	<LI><A href="apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</A></LI>
				285	<LI><A href="apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</A></LI>
				286	<LI><A href="download.html" title="Download">Download & Install </A></LI>
				287	</UL>
				288
				289
				290	<H6><A name="iPOJOJMXHandler-GettingStarted"></A><B>Getting Started</B></H6>
				291	<UL>
				292	<LI><A href="ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</A></LI>
				293	<LI><A href="ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</A></LI>
				294	<LI><A href="ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</A></LI>
				295	</UL>
				296
				297
				298	<H6><A name="iPOJOJMXHandler-UserGuide"></A><B>User Guide</B></H6>
				299	<UL>
				300	<LI><A href="describing-components.html" title="Describing components">Describing components (handler list) </A></LI>
				301	<LI><A href="how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</A></LI>
				302	<LI><A href="ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</A></LI>
				303	<LI><A href="ipojo-faq.html" title="iPOJO FAQ">FAQ</A></LI>
				304	</UL>
				305
				306
				307	<H6><A name="iPOJOJMXHandler-Tools"></A><B>Tools</B></H6>
				308	<UL>
				309	<LI><A href="ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</A></LI>
				310	<LI><A href="ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</A></LI>
				311	<LI><A href="ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</A></LI>
				312	<LI><A href="ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</A></LI>
				313	</UL>
				314
				315
				316	<H6><A name="iPOJOJMXHandler-DeveloperGuide"></A><B>Developer Guide</B></H6>
				317	<UL>
				318	<LI>API: <SPAN class="nobr"><A href="http://people.apache.org/~clement/ipojo/api/0.8/" title="Visit page outside Confluence" rel="nofollow">0.8<SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
				319	<LI><A href="how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</A></LI>
				320	<LI><A href="how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</A></LI>
				321	</UL>
				322
				323
				324	<H6><A name="iPOJOJMXHandler-Misc%26Contact"></A><B>Misc & Contact</B></H6>
				325	<UL>
				326	<LI><A href="apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</A></LI>
				327	<LI><A href="apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</A></LI>
				328	<LI><A href="apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</A></LI>
				329	<LI><A href="future-ideas.html" title="Future Ideas">Future Ideas</A></LI>
				330	<LI><A href="contact.html" title="Contact">Contact</A></LI>
				331	<LI><A href="related-works.html" title="Related Works">Related Works</A></LI>
				332	<LI><A href="article-presentations.html" title="Article & Presentations">Article & Presentations</A></LI>
				333	</UL>
				334
				335
				336	<HR>
				337	<DIV class="" align="center">
				338	<P><SPAN class="nobr"><A href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&statuses=created&statuses=modified&spaces=FELIX&labelString=iPOJO&rssType=atom&maxResults=10&timeSpan=5&publicFeed=true&title=iPOJO%20Atom%20Feed" title="Stay tuned!" rel="nofollow"><IMG src="../../cwiki.apache.org/confluence/images/icons/feed-icon-32x32.png" align="absmiddle" border="0"><SUP><IMG class="rendericon" src="../../cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></P></DIV></TD></TR></TBODY></TABLE>
				339	</DIV>
				340	</BODY>
				341
				342	<!-- Mirrored Site: felix.apache.org. File: /site/ipojo-jmx-handler.html. Date: Mon, 13 Oct 2008 06:53:08 GMT -->
				343	</HTML>