How to use

JmxSupport

in

brooklyn.entity.java

@Override
public void init() {
  super.init();
  new JmxSupport(this, null).recommendJmxRmiCustomAgent();
}

public synchronized Certificate getJmxAccessCert() {
  Certificate cert = jmxSupport.getConfig(UsesJmx.JMX_SSL_ACCESS_CERT);
  if (cert!=null) return cert;
  // TODO load from keyStoreUrl
  KeyPair jmxAccessKey = SecureKeys.newKeyPair();
  X509Certificate jmxAccessCert = getBrooklynRootSigner().newCertificateFor("brooklyn-jmx-access", jmxAccessKey);
  jmxSupport.setConfig(UsesJmx.JMX_SSL_ACCESS_CERT, jmxAccessCert);
  jmxSupport.setConfig(UsesJmx.JMX_SSL_ACCESS_KEY, jmxAccessKey.getPrivate());
  
  return jmxAccessCert;
}

/** mode NONE cannot set a JMX (RMI server) port; it needs an RMI registry port,
 * then gets redirected to an anonymous RMI server port;
 * both the hostname and the anonymous port must be accessible to use this mode
 * (hence the use of the other agents in most cases) */
protected int fixPortsForModeNone() {
  assert getJmxAgentMode()==JmxAgentModes.NONE;
  Integer jmxRemotePort = getEntity().getAttribute(JMX_PORT);
  Integer rmiRegistryPort = getEntity().getAttribute(RMI_REGISTRY_PORT);
  if (rmiRegistryPort!=null && rmiRegistryPort>0) {
    if (jmxRemotePort==null || jmxRemotePort!=rmiRegistryPort) {
      if (jmxRemotePort!=null && jmxRemotePort>0) {
        // ignore RMI registry port when mode 'none' is set -- set same as JMX port here
        // (bit irritating, but JMX_PORT will be ignored in this mode)
        log.warn("Ignoring JMX_PORT "+jmxRemotePort+" when configuring agentless JMX on "+getEntity()+"; will use RMI_REGISTRY_PORT "+rmiRegistryPort);
      }
      jmxRemotePort = rmiRegistryPort;
      ((EntityLocal)getEntity()).setAttribute(JMX_PORT, jmxRemotePort);
    }
  } else {
    if (jmxRemotePort==null || jmxRemotePort<=0) {
      throw new IllegalStateException("Invalid JMX_PORT "+jmxRemotePort+" and RMI_REGISTRY_PORT "+rmiRegistryPort+" when configuring JMX "+getJmxAgentMode()+" on "+getEntity());
    }
    ((EntityLocal)getEntity()).setAttribute(RMI_REGISTRY_PORT, jmxRemotePort);
  }
  return jmxRemotePort;
}

public String getJmxAgentJarDestinationFilePath() {
  return Urls.mergePaths(getRunDir(), getJmxAgentJarBasename());
}

/** @deprecated since 0.6.0; use {@link #getJmxAgentJarMavenArtifact()} */
@Deprecated
public String getJmxAgentJarBasename() {
  MavenArtifact artifact = getJmxAgentJarMavenArtifact();
  if (artifact==null)
    throw new IllegalStateException("Either JMX is not enabled or there is an error in the configuration (JMX mode "+getJmxAgentMode()+" does not support agent JAR)");
  return artifact.getFilename();
}

if (!isJmx()) return ;
String hostName = getEntity().getAttribute(Attributes.HOSTNAME);
if (hostName==null) hostName = checkNotNull(getMachine().get().getAddress().getHostName(), "hostname for entity " + entity);
switch (getJmxAgentMode()) {
case JMXMP:
  jmxRemotePort = getEntity().getAttribute(JMX_PORT);
  if (jmxRemotePort==null || jmxRemotePort<=0)
    throw new IllegalStateException("Unsupported JMX port "+jmxRemotePort+" - when applying system properties ("+getJmxAgentMode()+" / "+getEntity()+")");
  result.put(JmxmpAgent.JMXMP_PORT_PROPERTY, jmxRemotePort);
  break;
case JMX_RMI_CUSTOM_AGENT:    
  jmxRemotePort = getEntity().getAttribute(JMX_PORT);
  if (jmxRemotePort==null || jmxRemotePort<=0)
    throw new IllegalStateException("Unsupported JMX port "+jmxRemotePort+" - when applying system properties ("+getJmxAgentMode()+" / "+getEntity()+")");
  result.put(JmxRmiAgent.RMI_REGISTRY_PORT_PROPERTY, 
      Preconditions.checkNotNull(entity.getAttribute(UsesJmx.RMI_REGISTRY_PORT), "registry port"));
  jmxRemotePort = fixPortsForModeNone();
  result.put("com.sun.management.jmxremote.port", jmxRemotePort);
  result.put("java.rmi.server.hostname", hostName);
  break;
default:    
  throw new IllegalStateException("Unsupported JMX mode - when applying system properties ("+getJmxAgentMode()+" / "+getEntity()+")");
if (isSecure()) {

/** installs files needed for JMX, to the runDir given in constructor, assuming the runDir has been created */ 
public void install() {
  if (getJmxAgentMode()!=JmxAgentModes.NONE) {
    getMachine().get().copyTo(ResourceUtils.create(this).getResourceFromUrl(
      getJmxAgentJarUrl()), getJmxAgentJarDestinationFilePath());
  }
  if (isSecure()) {
    getJmxSslSupport().install();
  }
}

/** constructs a JMX URL suitable for connecting to the given entity, being smart about JMX/RMI vs JMXMP */
public static String toJmxUrl(EntityLocal entity) {
  String url = entity.getAttribute(UsesJmx.JMX_URL);
  if (url != null) {
    return url;
  } else {
    new JmxSupport(entity, null).setJmxUrl();
    url = entity.getAttribute(UsesJmx.JMX_URL);
    return Preconditions.checkNotNull(url, "Could not find URL for "+entity);
  }
}

/**
 * Return any JVM arguments required, other than the -D defines returned by {@link #getJmxJavaSystemProperties()}
 */
protected List<String> getJmxJavaConfigOptions() {
  List<String> result = new ArrayList<String>();
  if (isJmxEnabled()) {
    result.addAll(new JmxSupport(getEntity(), getRunDir()).getJmxJavaConfigOptions());
  }
  return result;
}
  

public void installJmxSupport() {
  if (isJmxEnabled()) {
    newScript("JMX_SETUP_PREINSTALL").body.append("mkdir -p "+getRunDir()).execute();
    new JmxSupport(getEntity(), getRunDir()).install();
  }
}

/**
 * Return the configuration properties required to enable JMX for a Java application.
 * 
 * These should be set as properties in the {@code JAVA_OPTS} environment variable when calling the
 * run script for the application.
 */
protected Map<String, ?> getJmxJavaSystemProperties() {
  MutableMap.Builder<String, Object> result = MutableMap.<String, Object> builder();
  
  if (isJmxEnabled()) {
    new JmxSupport(getEntity(), getRunDir()).applyJmxJavaSystemProperties(result);
  }
  
  return result.build();
}

public String getJmxUrl() {
  init();
  
  String host = entity.getAttribute(Attributes.HOSTNAME);
  if (host==null) {
    SshMachineLocation machine = EffectorTasks.getSshMachine(entity);
    host = machine.getAddress().getHostName();
  }
  
  if (getJmxAgentMode()==JmxAgentModes.JMXMP) {
    return JmxHelper.toJmxmpUrl(host, entity.getAttribute(JMX_PORT));
  } else {
    if (getJmxAgentMode()==JmxAgentModes.NONE) {
      fixPortsForModeNone();
    }
    // this will work for agent or agentless
    return JmxHelper.toRmiJmxUrl(host, 
        entity.getAttribute(JMX_PORT),
        entity.getAttribute(RMI_REGISTRY_PORT),
        entity.getAttribute(JMX_CONTEXT));
  }
}

if (isSecure()) {
  jmxAgentMode = JmxAgentModes.JMXMP;
} else {
  Optional<SshMachineLocation> m = getMachine();
  if (m.isPresent()) {
    SshMachineLocation ll = m.get();
    jmxAgentMode = JmxAgentModes.JMXMP;                    
  if (!ResourceUtils.create(this).doesUrlExist(getJmxAgentJarUrl())) {
    log.warn("JMX agent JAR not found ("+getJmxAgentJarUrl()+") when auto-detecting JMX settings for "+entity+"; " +
        "likely cause is an incomplete build (e.g. from Eclipse; run a maven build then retry in the IDE); "+
        "reverting to NONE (use built-in Java JMX support, which will not go through firewalls)");

public List<String> getJmxJavaConfigOptions() {
  if (getJmxAgentMode()==JmxAgentModes.NONE)
    return MutableList.of();
  return MutableList.of(String.format("-javaagent:%s", getJmxAgentJarDestinationFilePath()));
}

<T> T getConfig(ConfigKey<T> key) {
  return getEntity().getConfig(key);
}

public synchronized PrivateKey getJmxAccessKey() {
  PrivateKey key = jmxSupport.getConfig(UsesJmx.JMX_SSL_ACCESS_KEY);
  if (key!=null) return key;
  getJmxAccessCert();
  return jmxSupport.getConfig(UsesJmx.JMX_SSL_ACCESS_KEY);
}

@Nullable public MavenArtifact getJmxAgentJarMavenArtifact() {
  switch (getJmxAgentMode()) {
  case JMXMP: 
    MavenArtifact result = BrooklynMavenArtifacts.artifact(null, "brooklyn-jmxmp-agent", "jar", "with-dependencies");
    // the "with-dependencies" variant is needed; however the filename then has the classifier segment _replaced_ by "shaded" when this filename is created
    result.setCustomFileNameAfterArtifactMarker("shaded");
    result.setClassifierFileNameMarker("");
    return result;
  case JMX_RMI_CUSTOM_AGENT: 
    return BrooklynMavenArtifacts.jar("brooklyn-jmxrmi-agent");
  default:
    return null;
  }        
}

/** returns URL for accessing the java agent, throwing if not applicable;
 * prefers on classpath where it should be, but will fall back to taking from maven hosted 
 * (known problem in Eclipse where JARs are not always copied) 
 */
public String getJmxAgentJarUrl() {
  MavenArtifact artifact = getJmxAgentJarMavenArtifact();
  if (artifact==null)
    throw new IllegalStateException("Either JMX is not enabled or there is an error in the configuration (JMX mode "+getJmxAgentMode()+" does not support agent JAR)");
  String jar = "classpath://" + artifact.getFilename();
  if (ResourceUtils.create(this).doesUrlExist(jar))
    return jar;
  
  String result = MavenRetriever.localUrl(artifact);
  if (warnedAboutNotOnClasspath) {
    log.debug("JMX JAR for "+artifact+" is not on the classpath; taking from "+result);
  } else {
    log.warn("JMX JAR for "+artifact+" is not on the classpath; taking from "+result+" (subsequent similar messages will be logged at debug)");
    warnedAboutNotOnClasspath = true;
  }
  return result;
}

<T> T getConfig(HasConfigKey<T> key) {
  return getEntity().getConfig(key);
}

<T> void setConfig(ConfigKey<T> key, T value) {
  ((EntityLocal)getEntity()).setConfig(key, value);
}