Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revise reference documentation for Spring JMX annotations

Browse Source 
This commit revises the reference documentation for Spring JMX
annotations for various reasons including, but not limited to, the
following.

- Type names such as ManagedResource are often ambiguous, especially
  when discussing an annotation like @⁠ManagedResource instead of
  org.springframework.jmx.export.metadata.ManagedResource which is a
  class.
- AnnotationTestBean implements IJmxTestBean, even though an annotated
  MBean is not required to implement any interfaces, and in fact the
  example is meant to demonstrate that an annotated POJO suffices.
- @⁠ManagedOperationParameter annotations are unnecessarily declared in
  the @⁠ManagedOperationParameters container.
- The documentation sometimes refers to JmxTestBean when it should
  instead refer to AnnotationTestBean.
- Inconsistent and confusing wording for annotation attributes,
  properties, managed attributes, etc.
- The tables refer to "source-level metadata types/parameters" when
  they should refer to Spring JMX annotations and their attributes.
- The annotation and attribute tables have inconsistent ordering and
  naming for column headers.
- @⁠ManagedNotification and @⁠ManagedMetric are not mentioned.
- The AutodetectCapableMBeanInfoAssembler example is broken since it
  uses the non-annotated JmxTestBean instead of the AnnotationTestBean.

As a side note, the JmxTestBean in our test suite still contains
XDoclet "annotations" which can be safely removed. 😉

Closes gh-33466
This commit is contained in:
Sam Brannen
2024-09-02 18:18:10 +02:00
parent 6e640f0800
commit 1af6480217
9 changed files with 192 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
spring-context/src/test/java/org/springframework/jmx/IJmxTestBean.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -20,19 +20,15 @@ package org.springframework.jmx;
* @author Rob Harrop
* @author Juergen Hoeller
*/
public interface IJmxTestBean {
public interface IJmxTestBean extends ITestBean {
int add(int x, int y);
long myOperation();
int getAge();
void setAge(int age);
void setName(String name) throws Exception;
String getName();
int getAge();
// used to test invalid methods that exist in the proxy interface
void dontExposeMe();

25
spring-context/src/test/java/org/springframework/jmx/ITestBean.java Normal file
View File

@@ -0,0 +1,25 @@
/*
* Copyright 2002-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.jmx;
public interface ITestBean {
void setName(String name) throws Exception;
String getName();
}

54
spring-context/src/test/java/org/springframework/jmx/JmxTestBean.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2016 the original author or authors.
* Copyright 2002-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -19,12 +19,6 @@ package org.springframework.jmx;
import java.io.IOException;
/**
* @@org.springframework.jmx.export.metadata.ManagedResource
* (description="My Managed Bean", objectName="spring:bean=test",
* log=true, logFile="build/jmx.log", currencyTimeLimit=15, persistPolicy="OnUpdate",
* persistPeriod=200, persistLocation="./foo", persistName="bar.jmx")
* @@org.springframework.jmx.export.metadata.ManagedNotification
* (name="My Notification", description="A Notification", notificationType="type.foo,type.bar")
* @author Rob Harrop
* @author Juergen Hoeller
*/
@@ -39,33 +33,21 @@ public class JmxTestBean implements IJmxTestBean {
private boolean isSuperman;
/**
* @@org.springframework.jmx.export.metadata.ManagedAttribute
* (description="The Age Attribute", currencyTimeLimit=15)
*/
@Override
public void setAge(int age) {
this.age = age;
}
@Override
public int getAge() {
return age;
}
@Override
public void setAge(int age) {
this.age = age;
}
/**
* @@org.springframework.jmx.export.metadata.ManagedOperation(currencyTimeLimit=30)
*/
@Override
public long myOperation() {
return 1L;
}
/**
* @@org.springframework.jmx.export.metadata.ManagedAttribute
* (description="The Name Attribute", currencyTimeLimit=20,
* defaultValue="bar", persistPolicy="OnUpdate")
*/
@Override
public void setName(String name) throws Exception {
if ("Juergen".equals(name)) {
@@ -80,20 +62,11 @@ public class JmxTestBean implements IJmxTestBean {
this.name = name;
}
/**
* @@org.springframework.jmx.export.metadata.ManagedAttribute
* (defaultValue="foo", persistPeriod=300)
*/
@Override
public String getName() {
return name;
}
/**
* @@org.springframework.jmx.export.metadata.ManagedAttribute(description="The Nick
* Name
* Attribute")
*/
public void setNickName(String nickName) {
this.nickName = nickName;
}
@@ -106,30 +79,15 @@ public class JmxTestBean implements IJmxTestBean {
this.isSuperman = superman;
}
/**
* @@org.springframework.jmx.export.metadata.ManagedAttribute(description="The Is
* Superman
* Attribute")
*/
public boolean isSuperman() {
return isSuperman;
}
/**
* @@org.springframework.jmx.export.metadata.ManagedOperation(description="Add Two
* Numbers
* Together")
* @@org.springframework.jmx.export.metadata.ManagedOperationParameter(index=0, name="x", description="Left operand")
* @@org.springframework.jmx.export.metadata.ManagedOperationParameter(index=1, name="y", description="Right operand")
*/
@Override
public int add(int x, int y) {
return x + y;
}
/**
* Test method that is not exposed by the MetadataAssembler.
*/
@Override
public void dontExposeMe() {
throw new RuntimeException();

4
spring-context/src/test/java/org/springframework/jmx/export/annotation/AnnotationMetadataAssemblerTests.java
View File

@@ -22,7 +22,7 @@ import javax.management.modelmbean.ModelMBeanOperationInfo;
import org.junit.jupiter.api.Test;
import org.springframework.jmx.IJmxTestBean;
import org.springframework.jmx.ITestBean;
import org.springframework.jmx.export.assembler.AbstractMetadataAssemblerTests;
import org.springframework.jmx.export.metadata.JmxAttributeSource;
@@ -93,7 +93,7 @@ class AnnotationMetadataAssemblerTests extends AbstractMetadataAssemblerTests {
}
@Override
protected IJmxTestBean createJmxTestBean() {
protected ITestBean createJmxTestBean() {
return new AnnotationTestSubBean();
}

31
spring-context/src/test/java/org/springframework/jmx/export/annotation/AnnotationTestBean.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2018 the original author or authors.
* Copyright 2002-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@
package org.springframework.jmx.export.annotation;
import org.springframework.jmx.IJmxTestBean;
import org.springframework.jmx.ITestBean;
import org.springframework.jmx.support.MetricType;
import org.springframework.stereotype.Service;
@@ -29,7 +29,7 @@ import org.springframework.stereotype.Service;
logFile = "build/jmx.log", currencyTimeLimit = 15, persistPolicy = "OnUpdate", persistPeriod = 200,
persistLocation = "./foo", persistName = "bar.jmx")
@ManagedNotification(name = "My Notification", notificationTypes = { "type.foo", "type.bar" })
public class AnnotationTestBean implements IJmxTestBean {
public class AnnotationTestBean implements ITestBean {
private String name;
@@ -40,21 +40,13 @@ public class AnnotationTestBean implements IJmxTestBean {
private boolean isSuperman;
@Override
@ManagedAttribute(description = "The Age Attribute", currencyTimeLimit = 15)
public int getAge() {
return age;
}
@Override
public void setAge(int age) {
this.age = age;
}
@Override
@ManagedOperation(currencyTimeLimit = 30)
public long myOperation() {
return 1L;
@ManagedAttribute(description = "The Age Attribute", currencyTimeLimit = 15)
public int getAge() {
return this.age;
}
@Override
@@ -69,7 +61,7 @@ public class AnnotationTestBean implements IJmxTestBean {
@Override
@ManagedAttribute(defaultValue = "foo", persistPeriod = 300)
public String getName() {
return name;
return this.name;
}
@ManagedAttribute(description = "The Nick Name Attribute")
@@ -90,7 +82,11 @@ public class AnnotationTestBean implements IJmxTestBean {
return isSuperman;
}
@Override
@ManagedOperation(currencyTimeLimit = 30)
public long myOperation() {
return 1L;
}
@ManagedOperation(description = "Add Two Numbers Together")
@ManagedOperationParameter(name="x", description="Left operand")
@ManagedOperationParameter(name="y", description="Right operand")
@@ -99,9 +95,8 @@ public class AnnotationTestBean implements IJmxTestBean {
}
/**
* Test method that is not exposed by the MetadataAssembler.
* Method that is not exposed by the MetadataAssembler.
*/
@Override
public void dontExposeMe() {
throw new RuntimeException();
}

3
spring-context/src/test/java/org/springframework/jmx/export/annotation/AnnotationTestBeanFactory.java
View File

@@ -17,7 +17,6 @@
package org.springframework.jmx.export.annotation;
import org.springframework.beans.factory.FactoryBean;
import org.springframework.jmx.IJmxTestBean;
/**
* @author Juergen Hoeller
@@ -36,7 +35,7 @@ public class AnnotationTestBeanFactory implements FactoryBean<FactoryCreatedAnno
}
@Override
public Class<? extends IJmxTestBean> getObjectType() {
public Class<? extends AnnotationTestBean> getObjectType() {
return FactoryCreatedAnnotationTestBean.class;
}

89
spring-context/src/test/java/org/springframework/jmx/export/assembler/AbstractJmxAssemblerTests.java
View File

@@ -18,10 +18,8 @@ package org.springframework.jmx.export.assembler;
import javax.management.Attribute;
import javax.management.Descriptor;
import javax.management.MBeanAttributeInfo;
import javax.management.MBeanInfo;
import javax.management.MBeanNotificationInfo;
import javax.management.MBeanOperationInfo;
import javax.management.ObjectInstance;
import javax.management.ObjectName;
import javax.management.modelmbean.ModelMBeanAttributeInfo;
@@ -31,7 +29,7 @@ import javax.management.modelmbean.ModelMBeanOperationInfo;
import org.junit.jupiter.api.Test;
import org.springframework.jmx.AbstractJmxTests;
import org.springframework.jmx.IJmxTestBean;
import org.springframework.jmx.ITestBean;
import org.springframework.jmx.support.ObjectNameManager;
import static org.assertj.core.api.Assertions.assertThat;
@@ -48,76 +46,68 @@ public abstract class AbstractJmxAssemblerTests extends AbstractJmxTests {
protected abstract String getObjectName();
@Test
void testMBeanRegistration() throws Exception {
void mBeanRegistration() throws Exception {
// beans are registered at this point - just grab them from the server
ObjectInstance instance = getObjectInstance();
assertThat(instance).as("Bean should not be null").isNotNull();
}
@Test
void testRegisterOperations() throws Exception {
IJmxTestBean bean = getBean();
assertThat(bean).isNotNull();
void registerOperations() throws Exception {
assertThat(getBean()).isNotNull();
MBeanInfo inf = getMBeanInfo();
assertThat(inf.getOperations()).as("Incorrect number of operations registered").hasSize(getExpectedOperationCount());
}
@Test
void testRegisterAttributes() throws Exception {
IJmxTestBean bean = getBean();
assertThat(bean).isNotNull();
void registerAttributes() throws Exception {
assertThat(getBean()).isNotNull();
MBeanInfo inf = getMBeanInfo();
assertThat(inf.getAttributes()).as("Incorrect number of attributes registered").hasSize(getExpectedAttributeCount());
}
@Test
void testGetMBeanInfo() throws Exception {
void getMBeanAttributeInfo() throws Exception {
ModelMBeanInfo info = getMBeanInfoFromAssembler();
assertThat(info).as("MBeanInfo should not be null").isNotNull();
assertThat(info.getAttributes())
.hasSize(getExpectedAttributeCount())
.allSatisfy(element -> {
assertThat(element).as("MBeanAttributeInfo should not be null").isNotNull();
assertThat(element.getDescription()).as("Description for MBeanAttributeInfo should not be null").isNotNull();
});
}
@Test
void testGetMBeanAttributeInfo() throws Exception {
void getMBeanOperationInfo() throws Exception {
ModelMBeanInfo info = getMBeanInfoFromAssembler();
MBeanAttributeInfo[] inf = info.getAttributes();
assertThat(inf).as("Invalid number of Attributes returned").hasSize(getExpectedAttributeCount());
for (MBeanAttributeInfo element : inf) {
assertThat(element).as("MBeanAttributeInfo should not be null").isNotNull();
assertThat(element.getDescription()).as("Description for MBeanAttributeInfo should not be null").isNotNull();
}
assertThat(info).as("MBeanInfo should not be null").isNotNull();
assertThat(info.getOperations())
.hasSize(getExpectedOperationCount())
.allSatisfy(element -> {
assertThat(element).as("MBeanOperationInfo should not be null").isNotNull();
assertThat(element.getDescription()).as("Description for MBeanOperationInfo should not be null").isNotNull();
});
}
@Test
void testGetMBeanOperationInfo() throws Exception {
ModelMBeanInfo info = getMBeanInfoFromAssembler();
MBeanOperationInfo[] inf = info.getOperations();
assertThat(inf).as("Invalid number of Operations returned").hasSize(getExpectedOperationCount());
for (MBeanOperationInfo element : inf) {
assertThat(element).as("MBeanOperationInfo should not be null").isNotNull();
assertThat(element.getDescription()).as("Description for MBeanOperationInfo should not be null").isNotNull();
}
}
@Test
void testDescriptionNotNull() throws Exception {
void descriptionNotNull() throws Exception {
ModelMBeanInfo info = getMBeanInfoFromAssembler();
assertThat(info.getDescription()).as("The MBean description should not be null").isNotNull();
}
@Test
void testSetAttribute() throws Exception {
void setAttribute() throws Exception {
ObjectName objectName = ObjectNameManager.getInstance(getObjectName());
getServer().setAttribute(objectName, new Attribute(NAME_ATTRIBUTE, "Rob Harrop"));
IJmxTestBean bean = (IJmxTestBean) getContext().getBean("testBean");
assertThat(bean.getName()).isEqualTo("Rob Harrop");
assertThat(getBean().getName()).isEqualTo("Rob Harrop");
}
@Test
void testGetAttribute() throws Exception {
void getAttribute() throws Exception {
ObjectName objectName = ObjectNameManager.getInstance(getObjectName());
getBean().setName("John Smith");
Object val = getServer().getAttribute(objectName, NAME_ATTRIBUTE);
@@ -125,7 +115,7 @@ public abstract class AbstractJmxAssemblerTests extends AbstractJmxTests {
}
@Test
void testOperationInvocation() throws Exception{
void operationInvocation() throws Exception{
ObjectName objectName = ObjectNameManager.getInstance(getObjectName());
Object result = getServer().invoke(objectName, "add",
new Object[] {20, 30}, new String[] {"int", "int"});
@@ -133,7 +123,7 @@ public abstract class AbstractJmxAssemblerTests extends AbstractJmxTests {
}
@Test
void testAttributeInfoHasDescriptors() throws Exception {
void attributeInfoHasDescriptors() throws Exception {
ModelMBeanInfo info = getMBeanInfoFromAssembler();
ModelMBeanAttributeInfo attr = info.getAttribute(NAME_ATTRIBUTE);
@@ -145,42 +135,35 @@ public abstract class AbstractJmxAssemblerTests extends AbstractJmxTests {
}
@Test
void testAttributeHasCorrespondingOperations() throws Exception {
void attributeHasCorrespondingOperations() throws Exception {
ModelMBeanInfo info = getMBeanInfoFromAssembler();
ModelMBeanOperationInfo get = info.getOperation("getName");
assertThat(get).as("get operation should not be null").isNotNull();
assertThat(Integer.valueOf(4)).as("get operation should have visibility of four").isEqualTo(get.getDescriptor().getFieldValue("visibility"));
assertThat(get.getDescriptor().getFieldValue("visibility")).as("get operation should have visibility of four").isEqualTo(4);
assertThat(get.getDescriptor().getFieldValue("role")).as("get operation should have role \"getter\"").isEqualTo("getter");
ModelMBeanOperationInfo set = info.getOperation("setName");
assertThat(set).as("set operation should not be null").isNotNull();
assertThat(Integer.valueOf(4)).as("set operation should have visibility of four").isEqualTo(set.getDescriptor().getFieldValue("visibility"));
assertThat(set.getDescriptor().getFieldValue("visibility")).as("set operation should have visibility of four").isEqualTo(4);
assertThat(set.getDescriptor().getFieldValue("role")).as("set operation should have role \"setter\"").isEqualTo("setter");
}
@Test
void testNotificationMetadata() throws Exception {
void notificationMetadata() throws Exception {
ModelMBeanInfo info = (ModelMBeanInfo) getMBeanInfo();
MBeanNotificationInfo[] notifications = info.getNotifications();
assertThat(notifications).as("Incorrect number of notifications").hasSize(1);
assertThat(notifications[0].getName()).as("Incorrect notification name").isEqualTo("My Notification");
String[] notifTypes = notifications[0].getNotifTypes();
assertThat(notifTypes).as("Incorrect number of notification types").hasSize(2);
assertThat(notifTypes[0]).as("Notification type.foo not found").isEqualTo("type.foo");
assertThat(notifTypes[1]).as("Notification type.bar not found").isEqualTo("type.bar");
assertThat(notifications[0].getNotifTypes()).as("notification types").containsExactly("type.foo", "type.bar");
}
protected ModelMBeanInfo getMBeanInfoFromAssembler() throws Exception {
IJmxTestBean bean = getBean();
return getAssembler().getMBeanInfo(bean, getObjectName());
return getAssembler().getMBeanInfo(getBean(), getObjectName());
}
protected IJmxTestBean getBean() {
Object bean = getContext().getBean("testBean");
return (IJmxTestBean) bean;
protected ITestBean getBean() {
return getContext().getBean("testBean", ITestBean.class);
}
protected MBeanInfo getMBeanInfo() throws Exception {

6
spring-context/src/test/java/org/springframework/jmx/export/assembler/AbstractMetadataAssemblerTests.java
View File

@@ -30,7 +30,7 @@ import org.junit.jupiter.api.Test;
import org.springframework.aop.framework.ProxyFactory;
import org.springframework.aop.testfixture.interceptor.NopInterceptor;
import org.springframework.jmx.IJmxTestBean;
import org.springframework.jmx.ITestBean;
import org.springframework.jmx.JmxTestBean;
import org.springframework.jmx.export.MBeanExporter;
import org.springframework.jmx.export.metadata.JmxAttributeSource;
@@ -156,7 +156,7 @@ public abstract class AbstractMetadataAssemblerTests extends AbstractJmxAssemble
@Test
void testWithCglibProxy() throws Exception {
IJmxTestBean tb = createJmxTestBean();
Object tb = createJmxTestBean();
ProxyFactory pf = new ProxyFactory();
pf.setTarget(tb);
pf.addAdvice(new NopInterceptor());
@@ -230,7 +230,7 @@ public abstract class AbstractMetadataAssemblerTests extends AbstractJmxAssemble
return 9;
}
protected IJmxTestBean createJmxTestBean() {
protected ITestBean createJmxTestBean() {
return new JmxTestBean();
}