diff --git oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/AnnotatedStandardMBean.java oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/AnnotatedStandardMBean.java new file mode 100644 index 0000000..2d78251 --- /dev/null +++ oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/AnnotatedStandardMBean.java @@ -0,0 +1,100 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 + * + * http://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.apache.jackrabbit.oak.commons.jmx; + +import javax.management.DescriptorRead; +import javax.management.MBeanAttributeInfo; +import javax.management.MBeanInfo; +import javax.management.MBeanOperationInfo; +import javax.management.MBeanParameterInfo; +import javax.management.NotCompliantMBeanException; +import javax.management.StandardMBean; + +/** + * The extension of {@link javax.management.StandardMBean} that will automatically provide JMX + * metadata through annotations. + * + * @see javax.management.MBeanInfo + * @see Description + * @see Name + * @see Impact + */ +public class AnnotatedStandardMBean extends StandardMBean { + /** + * Make a DynamicMBean out of the object implementation, using the specified + * mbeanInterface class. + * + * @see {@link javax.management.StandardMBean#StandardMBean(Object, Class)} + */ + public AnnotatedStandardMBean(T implementation, Class mbeanInterface) + throws NotCompliantMBeanException { + super(implementation, mbeanInterface); + } + + protected AnnotatedStandardMBean(Class mbeanInterface) + throws NotCompliantMBeanException { + super(mbeanInterface); + } + + @Override + protected String getDescription(MBeanInfo info) { + String desc = getValue(info, Description.NAME); + return desc == null ? super.getDescription(info) : desc; + } + + @Override + protected String getDescription(MBeanAttributeInfo info) { + String desc = getValue(info, Description.NAME); + return desc == null ? super.getDescription(info) : desc; + } + + @Override + protected String getDescription(MBeanOperationInfo info) { + String desc = getValue(info, Description.NAME); + return desc == null ? super.getDescription(info) : desc; + } + + @Override + protected int getImpact(MBeanOperationInfo info) { + String opt = (String)info.getDescriptor().getFieldValue(Impact.NAME); + return opt == null ? super.getImpact(info) : ImpactOption.valueOf(opt).value(); + } + + @Override + protected String getParameterName(MBeanOperationInfo op, + MBeanParameterInfo param, int sequence) { + String name = getValue(param, Name.NAME); + return name == null + ? super.getParameterName(op, param, sequence) + : name; + } + + @Override + protected String getDescription(MBeanOperationInfo op, + MBeanParameterInfo param, int sequence) { + String desc = getValue(param, Description.NAME); + return desc == null + ? super.getDescription(op, param, sequence) + : desc; + } + + private static String getValue(DescriptorRead dr, String fieldName){ + return (String) dr.getDescriptor().getFieldValue(fieldName); + } +} diff --git oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Description.java oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Description.java new file mode 100644 index 0000000..c18d28f --- /dev/null +++ oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Description.java @@ -0,0 +1,43 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 + * + * http://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.apache.jackrabbit.oak.commons.jmx; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import javax.management.DescriptorKey; + +/** + * Produces a description that will be used by JMX metadata. + */ +@Target({ElementType.TYPE, ElementType.CONSTRUCTOR, ElementType.METHOD, + ElementType.PARAMETER}) +@Retention(RetentionPolicy.RUNTIME) +@Inherited +@Documented +public @interface Description { + String NAME = "description"; + + @DescriptorKey(NAME) + String value() default ""; +} diff --git oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Impact.java oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Impact.java new file mode 100644 index 0000000..083df17 --- /dev/null +++ oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Impact.java @@ -0,0 +1,43 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 + * + * http://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.apache.jackrabbit.oak.commons.jmx; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import javax.management.DescriptorKey; + +/** + * Produces an operation impact that will be returned by JMX + * {@link javax.management.MBeanOperationInfo#getImpact()}. + */ +@Target({ElementType.METHOD}) +@Retention(RetentionPolicy.RUNTIME) +@Inherited +@Documented +public @interface Impact { + String NAME = "impact"; + + @DescriptorKey(NAME) + ImpactOption value(); +} diff --git oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/ImpactOption.java oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/ImpactOption.java new file mode 100644 index 0000000..441b1ad --- /dev/null +++ oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/ImpactOption.java @@ -0,0 +1,54 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 + * + * http://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.apache.jackrabbit.oak.commons.jmx; + +import javax.management.MBeanOperationInfo; + +public enum ImpactOption { + /** + * Indicates that the operation is a write-like, + * and would modify the MBean in some way, typically by writing some value + * or changing a configuration. + */ + ACTION(MBeanOperationInfo.ACTION), + /** + * Indicates that the operation is both read-like and write-like. + */ + ACTION_INFO(MBeanOperationInfo.ACTION_INFO), + /** + * Indicates that the operation is read-like, + * it basically returns information. + */ + INFO(MBeanOperationInfo.INFO), + /** + * Indicates that the operation has an "unknown" nature. + */ + UNKNOWN(MBeanOperationInfo.UNKNOWN); + + public int value(){ + return value; + } + + private final int value; + + private ImpactOption(int value) { + this.value = value; + } +} diff --git oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Name.java oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Name.java new file mode 100644 index 0000000..f8ba9cb --- /dev/null +++ oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/Name.java @@ -0,0 +1,43 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 + * + * http://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.apache.jackrabbit.oak.commons.jmx; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import javax.management.DescriptorKey; + +/** + * Produces a parameter name that will be returned by JMX + * {@link javax.management.MBeanParameterInfo#getName()}. + */ +@Target({ElementType.PARAMETER}) +@Retention(RetentionPolicy.RUNTIME) +@Inherited +@Documented +public @interface Name { + String NAME = "name"; + + @DescriptorKey(NAME) + String value(); +} diff --git oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/package-info.java oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/package-info.java new file mode 100644 index 0000000..2c57af9 --- /dev/null +++ oak-commons/src/main/java/org/apache/jackrabbit/oak/commons/jmx/package-info.java @@ -0,0 +1,31 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 + * + * http://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. + */ + +/** + * Provides annotation support to produce JMX metadata. + * + * @version 1.0 + */ +@Version("1.0") +@Export(optional = "provide:=true") +package org.apache.jackrabbit.oak.commons.jmx; + +import aQute.bnd.annotation.Export; +import aQute.bnd.annotation.Version; + diff --git oak-commons/src/test/java/org/apache/jackrabbit/oak/commons/jmx/AnnotatedStandardMBeanTest.java oak-commons/src/test/java/org/apache/jackrabbit/oak/commons/jmx/AnnotatedStandardMBeanTest.java new file mode 100644 index 0000000..eb95582 --- /dev/null +++ oak-commons/src/test/java/org/apache/jackrabbit/oak/commons/jmx/AnnotatedStandardMBeanTest.java @@ -0,0 +1,123 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 + * + * http://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.apache.jackrabbit.oak.commons.jmx; + +import java.lang.management.ManagementFactory; + +import javax.management.MBeanAttributeInfo; +import javax.management.MBeanConstructorInfo; +import javax.management.MBeanInfo; +import javax.management.MBeanOperationInfo; +import javax.management.MBeanParameterInfo; +import javax.management.MBeanServer; +import javax.management.ObjectName; + +import junit.framework.Assert; +import org.junit.AfterClass; +import org.junit.BeforeClass; +import org.junit.Test; + +import static junit.framework.Assert.assertEquals; + +public class AnnotatedStandardMBeanTest { + protected static ObjectName objectName; + + protected static MBeanServer server; + + @BeforeClass + public static void init() throws Exception { + AnnotatedStandardMBean object = new AnnotatedStandardMBean(new Foo(), + FooMBean.class); + + objectName = new ObjectName("abc:TYPE=Test"); + + server = ManagementFactory.getPlatformMBeanServer(); + server.registerMBean(object, objectName); + } + + @AfterClass + public static void tearDown() throws Exception { + server.unregisterMBean(objectName); + } + + @Test + public void test() throws Exception { + MBeanInfo info = server.getMBeanInfo(objectName); + + assertEquals("MBean desc.", info.getDescription()); + + MBeanAttributeInfo a0 = findAttribute(info, "Getter"); + assertEquals("getter", a0.getDescription()); + + MBeanAttributeInfo a1 = findAttribute(info, "It"); + assertEquals("is", a1.getDescription()); + + MBeanAttributeInfo a2 = findAttribute(info, "Setter"); + assertEquals("setter", a2.getDescription()); + + MBeanOperationInfo op0 = info.getOperations()[0]; + assertEquals("run", op0.getDescription()); + assertEquals(MBeanOperationInfo.INFO, op0.getImpact()); + + MBeanParameterInfo p0 = op0.getSignature()[0]; + assertEquals("timeout", p0.getName()); + assertEquals("how long?", p0.getDescription()); + } + + private MBeanAttributeInfo findAttribute(MBeanInfo info, String name) { + for (MBeanAttributeInfo a : info.getAttributes()) { + if (a.getName().equals(name)) return a; + } + + return null; + } + + @Description("MBean desc.") + public interface FooMBean { + @Description("getter") + String getGetter(); + + @Description("is") + boolean isIt(); + + @Description("setter") + void setSetter(long s); + + @Description("run") + @Impact(ImpactOption.INFO) + void run(@Name("timeout") @Description("how long?") long timeout); + } + + public static class Foo implements FooMBean { + + public String getGetter() { + return null; + } + + public boolean isIt() { + return false; + } + + public void setSetter(long s) { + } + + public void run(long timeout) { + } + } +}