Merge branch 'master' into ff/java
[collectd.git] / src / java.c
index bdfba76..984d29a 100644 (file)
@@ -102,9 +102,14 @@ static pthread_mutex_t       java_callbacks_lock = PTHREAD_MUTEX_INITIALIZER;
 /*
  * Prototypes
  *
- * Mostly functions that are needed by the Java interface functions.
+ * Mostly functions that are needed by the Java interface (``native'')
+ * functions.
  */
 static void cjni_callback_info_destroy (void *arg);
+static cjni_callback_info_t *cjni_callback_info_create (JNIEnv *jvm_env,
+    jobject o_name, jobject o_callback, int type);
+static int cjni_callback_register (JNIEnv *jvm_env, jobject o_name,
+    jobject o_callback, int type);
 static int cjni_read (user_data_t *user_data);
 static int cjni_write (const data_set_t *ds, const value_list_t *vl,
     user_data_t *ud);
@@ -723,6 +728,7 @@ static int ctoj_value_list_add_data_set (JNIEnv *jvm_env, /* {{{ */
   return (0);
 } /* }}} int ctoj_value_list_add_data_set */
 
+/* Convert a value_list_t (and data_set_t) to a org.collectd.api.ValueList */
 static jobject ctoj_value_list (JNIEnv *jvm_env, /* {{{ */
     const data_set_t *ds, const value_list_t *vl)
 {
@@ -831,6 +837,7 @@ static jobject ctoj_value_list (JNIEnv *jvm_env, /* {{{ */
 /*
  * Java to C conversion functions
  */
+/* Call a `String <method> ()' method. */
 static int jtoc_string (JNIEnv *jvm_env, /* {{{ */
     char *buffer, size_t buffer_size,
     jclass class_ptr, jobject object_ptr, const char *method_name)
@@ -872,6 +879,7 @@ static int jtoc_string (JNIEnv *jvm_env, /* {{{ */
   return (0);
 } /* }}} int jtoc_string */
 
+/* Call a `long <method> ()' method. */
 static int jtoc_long (JNIEnv *jvm_env, /* {{{ */
     jlong *ret_value,
     jclass class_ptr, jobject object_ptr, const char *method_name)
@@ -892,6 +900,7 @@ static int jtoc_long (JNIEnv *jvm_env, /* {{{ */
   return (0);
 } /* }}} int jtoc_long */
 
+/* Call a `double <method> ()' method. */
 static int jtoc_double (JNIEnv *jvm_env, /* {{{ */
     jdouble *ret_value,
     jclass class_ptr, jobject object_ptr, const char *method_name)
@@ -952,6 +961,8 @@ static int jtoc_value (JNIEnv *jvm_env, /* {{{ */
   return (0);
 } /* }}} int jtoc_value */
 
+/* Read a List<Number>, convert it to `value_t' and add it to the given
+ * `value_list_t'. */
 static int jtoc_values_array (JNIEnv *jvm_env, /* {{{ */
     const data_set_t *ds, value_list_t *vl,
     jclass class_ptr, jobject object_ptr)
@@ -1016,7 +1027,7 @@ static int jtoc_values_array (JNIEnv *jvm_env, /* {{{ */
     BAIL_OUT (-1);
   }
 
-  values = calloc (values_num, sizeof (value_t));
+  values = (value_t *) calloc (values_num, sizeof (value_t));
   if (values == NULL)
   {
     ERROR ("java plugin: jtoc_values_array: calloc failed.");
@@ -1126,6 +1137,190 @@ static int jtoc_value_list (JNIEnv *jvm_env, value_list_t *vl, /* {{{ */
   return (0);
 } /* }}} int jtoc_value_list */
 
+/* 
+ * Functions accessible from Java
+ */
+static jint JNICALL cjni_api_dispatch_values (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jobject java_vl)
+{
+  value_list_t vl = VALUE_LIST_INIT;
+  int status;
+
+  DEBUG ("cjni_api_dispatch_values: java_vl = %p;", (void *) java_vl);
+
+  status = jtoc_value_list (jvm_env, &vl, java_vl);
+  if (status != 0)
+  {
+    ERROR ("java plugin: cjni_api_dispatch_values: jtoc_value_list failed.");
+    return (-1);
+  }
+
+  status = plugin_dispatch_values (&vl);
+
+  sfree (vl.values);
+
+  return (status);
+} /* }}} jint cjni_api_dispatch_values */
+
+static jobject JNICALL cjni_api_get_ds (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jobject o_string_type)
+{
+  const char *ds_name;
+  const data_set_t *ds;
+  jobject o_dataset;
+
+  ds_name = (*jvm_env)->GetStringUTFChars (jvm_env, o_string_type, 0);
+  if (ds_name == NULL)
+  {
+    ERROR ("java plugin: cjni_api_get_ds: GetStringUTFChars failed.");
+    return (NULL);
+  }
+
+  ds = plugin_get_ds (ds_name);
+  DEBUG ("java plugin: cjni_api_get_ds: "
+      "plugin_get_ds (%s) = %p;", ds_name, (void *) ds);
+
+  (*jvm_env)->ReleaseStringUTFChars (jvm_env, o_string_type, ds_name);
+
+  if (ds == NULL)
+    return (NULL);
+
+  o_dataset = ctoj_data_set (jvm_env, ds);
+  return (o_dataset);
+} /* }}} jint cjni_api_get_ds */
+
+static jint JNICALL cjni_api_register_config (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jobject o_name, jobject o_config)
+{
+  return (cjni_callback_register (jvm_env, o_name, o_config, CB_TYPE_CONFIG));
+} /* }}} jint cjni_api_register_config */
+
+static jint JNICALL cjni_api_register_init (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jobject o_name, jobject o_config)
+{
+  return (cjni_callback_register (jvm_env, o_name, o_config, CB_TYPE_INIT));
+} /* }}} jint cjni_api_register_init */
+
+static jint JNICALL cjni_api_register_read (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jobject o_name, jobject o_read)
+{
+  user_data_t ud;
+  cjni_callback_info_t *cbi;
+
+  cbi = cjni_callback_info_create (jvm_env, o_name, o_read, CB_TYPE_READ);
+  if (cbi == NULL)
+    return (-1);
+
+  DEBUG ("java plugin: Registering new read callback: %s", cbi->name);
+
+  memset (&ud, 0, sizeof (ud));
+  ud.data = (void *) cbi;
+  ud.free_func = cjni_callback_info_destroy;
+
+  plugin_register_complex_read (cbi->name, cjni_read, &ud);
+
+  (*jvm_env)->DeleteLocalRef (jvm_env, o_read);
+
+  return (0);
+} /* }}} jint cjni_api_register_read */
+
+static jint JNICALL cjni_api_register_write (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jobject o_name, jobject o_write)
+{
+  user_data_t ud;
+  cjni_callback_info_t *cbi;
+
+  cbi = cjni_callback_info_create (jvm_env, o_name, o_write, CB_TYPE_WRITE);
+  if (cbi == NULL)
+    return (-1);
+
+  DEBUG ("java plugin: Registering new write callback: %s", cbi->name);
+
+  memset (&ud, 0, sizeof (ud));
+  ud.data = (void *) cbi;
+  ud.free_func = cjni_callback_info_destroy;
+
+  plugin_register_write (cbi->name, cjni_write, &ud);
+
+  (*jvm_env)->DeleteLocalRef (jvm_env, o_write);
+
+  return (0);
+} /* }}} jint cjni_api_register_write */
+
+static jint JNICALL cjni_api_register_shutdown (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jobject o_name, jobject o_shutdown)
+{
+  return (cjni_callback_register (jvm_env, o_name, o_shutdown,
+        CB_TYPE_SHUTDOWN));
+} /* }}} jint cjni_api_register_shutdown */
+
+static void JNICALL cjni_api_log (JNIEnv *jvm_env, /* {{{ */
+    jobject this, jint severity, jobject o_message)
+{
+  const char *c_str;
+
+  c_str = (*jvm_env)->GetStringUTFChars (jvm_env, o_message, 0);
+  if (c_str == NULL)
+  {
+    ERROR ("java plugin: cjni_api_log: GetStringUTFChars failed.");
+    return;
+  }
+
+  if (severity < LOG_ERR)
+    severity = LOG_ERR;
+  if (severity > LOG_DEBUG)
+    severity = LOG_DEBUG;
+
+  plugin_log (severity, "%s", c_str);
+
+  (*jvm_env)->ReleaseStringUTFChars (jvm_env, o_message, c_str);
+} /* }}} void cjni_api_log */
+
+/* List of ``native'' functions, i. e. C-functions that can be called from
+ * Java. */
+static JNINativeMethod jni_api_functions[] = /* {{{ */
+{
+  { "dispatchValues",
+    "(Lorg/collectd/api/ValueList;)I",
+    cjni_api_dispatch_values },
+
+  { "getDS",
+    "(Ljava/lang/String;)Lorg/collectd/api/DataSet;",
+    cjni_api_get_ds },
+
+  { "registerConfig",
+    "(Ljava/lang/String;Lorg/collectd/api/CollectdConfigInterface;)I",
+    cjni_api_register_config },
+
+  { "registerInit",
+    "(Ljava/lang/String;Lorg/collectd/api/CollectdInitInterface;)I",
+    cjni_api_register_init },
+
+  { "registerRead",
+    "(Ljava/lang/String;Lorg/collectd/api/CollectdReadInterface;)I",
+    cjni_api_register_read },
+
+  { "registerWrite",
+    "(Ljava/lang/String;Lorg/collectd/api/CollectdWriteInterface;)I",
+    cjni_api_register_write },
+
+  { "registerShutdown",
+    "(Ljava/lang/String;Lorg/collectd/api/CollectdShutdownInterface;)I",
+    cjni_api_register_shutdown },
+
+  { "log",
+    "(ILjava/lang/String;)V",
+    cjni_api_log },
+};
+static size_t jni_api_functions_num = sizeof (jni_api_functions)
+  / sizeof (jni_api_functions[0]);
+/* }}} */
+
+/*
+ * Functions
+ */
+/* Allocate a `cjni_callback_info_t' given the type and objects necessary for
+ * all registration functions. */
 static cjni_callback_info_t *cjni_callback_info_create (JNIEnv *jvm_env, /* {{{ */
     jobject o_name, jobject o_callback, int type)
 {
@@ -1137,27 +1332,27 @@ static cjni_callback_info_t *cjni_callback_info_create (JNIEnv *jvm_env, /* {{{
   switch (type)
   {
     case CB_TYPE_CONFIG:
-      method_name = "Config";
+      method_name = "config";
       method_signature = "(Lorg/collectd/api/OConfigItem;)I";
       break;
 
     case CB_TYPE_INIT:
-      method_name = "Init";
+      method_name = "init";
       method_signature = "()I";
       break;
 
     case CB_TYPE_READ:
-      method_name = "Read";
+      method_name = "read";
       method_signature = "()I";
       break;
 
     case CB_TYPE_WRITE:
-      method_name = "Write";
+      method_name = "write";
       method_signature = "(Lorg/collectd/api/ValueList;)I";
       break;
 
     case CB_TYPE_SHUTDOWN:
-      method_name = "Shutdown";
+      method_name = "shutdown";
       method_signature = "()I";
       break;
 
@@ -1222,6 +1417,9 @@ static cjni_callback_info_t *cjni_callback_info_create (JNIEnv *jvm_env, /* {{{
   return (cbi);
 } /* }}} cjni_callback_info_t cjni_callback_info_create */
 
+/* Allocate a `cjni_callback_info_t' via `cjni_callback_info_create' and add it
+ * to the global `java_callbacks' variable. This is used for `config', `init',
+ * and `shutdown' callbacks. */
 static int cjni_callback_register (JNIEnv *jvm_env, /* {{{ */
     jobject o_name, jobject o_callback, int type)
 {
@@ -1281,161 +1479,8 @@ static int cjni_callback_register (JNIEnv *jvm_env, /* {{{ */
   return (0);
 } /* }}} int cjni_callback_register */
 
-/* 
- * Functions accessible from Java
- */
-static jint JNICALL cjni_api_dispatch_values (JNIEnv *jvm_env, /* {{{ */
-    jobject this, jobject java_vl)
-{
-  value_list_t vl = VALUE_LIST_INIT;
-  int status;
-
-  DEBUG ("cjni_api_dispatch_values: java_vl = %p;", (void *) java_vl);
-
-  status = jtoc_value_list (jvm_env, &vl, java_vl);
-  if (status != 0)
-  {
-    ERROR ("java plugin: cjni_api_dispatch_values: jtoc_value_list failed.");
-    return (-1);
-  }
-
-  status = plugin_dispatch_values (&vl);
-
-  sfree (vl.values);
-
-  return (status);
-} /* }}} jint cjni_api_dispatch_values */
-
-static jobject JNICALL cjni_api_get_ds (JNIEnv *jvm_env, /* {{{ */
-    jobject this, jobject o_string_type)
-{
-  const char *ds_name;
-  const data_set_t *ds;
-  jobject o_dataset;
-
-  ds_name = (*jvm_env)->GetStringUTFChars (jvm_env, o_string_type, 0);
-  if (ds_name == NULL)
-  {
-    ERROR ("java plugin: cjni_api_get_ds: GetStringUTFChars failed.");
-    return (NULL);
-  }
-
-  ds = plugin_get_ds (ds_name);
-  DEBUG ("java plugin: cjni_api_get_ds: "
-      "plugin_get_ds (%s) = %p;", ds_name, (void *) ds);
-
-  (*jvm_env)->ReleaseStringUTFChars (jvm_env, o_string_type, ds_name);
-
-  if (ds == NULL)
-    return (NULL);
-
-  o_dataset = ctoj_data_set (jvm_env, ds);
-  return (o_dataset);
-} /* }}} jint cjni_api_get_ds */
-
-static jint JNICALL cjni_api_register_config (JNIEnv *jvm_env, /* {{{ */
-    jobject this, jobject o_name, jobject o_config)
-{
-  return (cjni_callback_register (jvm_env, o_name, o_config, CB_TYPE_CONFIG));
-} /* }}} jint cjni_api_register_config */
-
-static jint JNICALL cjni_api_register_init (JNIEnv *jvm_env, /* {{{ */
-    jobject this, jobject o_name, jobject o_config)
-{
-  return (cjni_callback_register (jvm_env, o_name, o_config, CB_TYPE_INIT));
-} /* }}} jint cjni_api_register_init */
-
-static jint JNICALL cjni_api_register_read (JNIEnv *jvm_env, /* {{{ */
-    jobject this, jobject o_name, jobject o_read)
-{
-  user_data_t ud;
-  cjni_callback_info_t *cbi;
-
-  cbi = cjni_callback_info_create (jvm_env, o_name, o_read, CB_TYPE_READ);
-  if (cbi == NULL)
-    return (-1);
-
-  DEBUG ("java plugin: Registering new read callback: %s", cbi->name);
-
-  memset (&ud, 0, sizeof (ud));
-  ud.data = (void *) cbi;
-  ud.free_func = cjni_callback_info_destroy;
-
-  plugin_register_complex_read (cbi->name, cjni_read, &ud);
-
-  (*jvm_env)->DeleteLocalRef (jvm_env, o_read);
-
-  return (0);
-} /* }}} jint cjni_api_register_read */
-
-static jint JNICALL cjni_api_register_write (JNIEnv *jvm_env, /* {{{ */
-    jobject this, jobject o_name, jobject o_write)
-{
-  user_data_t ud;
-  cjni_callback_info_t *cbi;
-
-  cbi = cjni_callback_info_create (jvm_env, o_name, o_write, CB_TYPE_WRITE);
-  if (cbi == NULL)
-    return (-1);
-
-  DEBUG ("java plugin: Registering new write callback: %s", cbi->name);
-
-  memset (&ud, 0, sizeof (ud));
-  ud.data = (void *) cbi;
-  ud.free_func = cjni_callback_info_destroy;
-
-  plugin_register_write (cbi->name, cjni_write, &ud);
-
-  (*jvm_env)->DeleteLocalRef (jvm_env, o_write);
-
-  return (0);
-} /* }}} jint cjni_api_register_write */
-
-static jint JNICALL cjni_api_register_shutdown (JNIEnv *jvm_env, /* {{{ */
-    jobject this, jobject o_name, jobject o_shutdown)
-{
-  return (cjni_callback_register (jvm_env, o_name, o_shutdown,
-        CB_TYPE_SHUTDOWN));
-} /* }}} jint cjni_api_register_shutdown */
-
-static JNINativeMethod jni_api_functions[] = /* {{{ */
-{
-  { "DispatchValues",
-    "(Lorg/collectd/api/ValueList;)I",
-    cjni_api_dispatch_values },
-
-  { "GetDS",
-    "(Ljava/lang/String;)Lorg/collectd/api/DataSet;",
-    cjni_api_get_ds },
-
-  { "RegisterConfig",
-    "(Ljava/lang/String;Lorg/collectd/api/CollectdConfigInterface;)I",
-    cjni_api_register_config },
-
-  { "RegisterInit",
-    "(Ljava/lang/String;Lorg/collectd/api/CollectdInitInterface;)I",
-    cjni_api_register_init },
-
-  { "RegisterRead",
-    "(Ljava/lang/String;Lorg/collectd/api/CollectdReadInterface;)I",
-    cjni_api_register_read },
-
-  { "RegisterWrite",
-    "(Ljava/lang/String;Lorg/collectd/api/CollectdWriteInterface;)I",
-    cjni_api_register_write },
-
-  { "RegisterShutdown",
-    "(Ljava/lang/String;Lorg/collectd/api/CollectdShutdownInterface;)I",
-    cjni_api_register_shutdown }
-
-};
-static size_t jni_api_functions_num = sizeof (jni_api_functions)
-  / sizeof (jni_api_functions[0]);
-/* }}} */
-
-/*
- * Functions
- */
+/* Increase the reference counter to the JVM for this thread. If it was zero,
+ * attach the JVM first. */
 static JNIEnv *cjni_thread_attach (void) /* {{{ */
 {
   cjni_jvm_env_t *cjni_env;
@@ -1491,6 +1536,8 @@ static JNIEnv *cjni_thread_attach (void) /* {{{ */
   return (jvm_env);
 } /* }}} JNIEnv *cjni_thread_attach */
 
+/* Decrease the reference counter of this thread. If it reaches zero, detach
+ * from the JVM. */
 static int cjni_thread_detach (void) /* {{{ */
 {
   cjni_jvm_env_t *cjni_env;
@@ -1526,6 +1573,8 @@ static int cjni_thread_detach (void) /* {{{ */
   return (0);
 } /* }}} JNIEnv *cjni_thread_attach */
 
+/* Callback for `pthread_key_create'. It frees the data contained in
+ * `jvm_env_key' and prints a warning if the reference counter is not zero. */
 static void cjni_jvm_env_destroy (void *args) /* {{{ */
 {
   cjni_jvm_env_t *cjni_env;
@@ -1551,38 +1600,7 @@ static void cjni_jvm_env_destroy (void *args) /* {{{ */
   free (cjni_env);
 } /* }}} void cjni_jvm_env_destroy */
 
-/* 
- * Delete a global reference, set by the various `Register*' functions.
- */
-static void cjni_callback_info_destroy (void *arg) /* {{{ */
-{
-  JNIEnv *jvm_env;
-  cjni_callback_info_t *cbi;
-
-  DEBUG ("java plugin: cjni_callback_info_destroy (arg = %p);", arg);
-
-  if (arg == NULL)
-    return;
-
-  jvm_env = cjni_thread_attach ();
-  if (jvm_env == NULL)
-  {
-    ERROR ("java plugin: cjni_callback_info_destroy: cjni_thread_attach failed.");
-    return;
-  }
-
-  cbi = (cjni_callback_info_t *) arg;
-
-  (*jvm_env)->DeleteGlobalRef (jvm_env, cbi->object);
-
-  cbi->method = NULL;
-  cbi->object = NULL;
-  cbi->class  = NULL;
-  free (cbi);
-
-  cjni_thread_detach ();
-} /* }}} void cjni_callback_info_destroy */
-
+/* Boring configuration functions.. {{{ */
 static int cjni_config_add_jvm_arg (oconfig_item_t *ci) /* {{{ */
 {
   char **tmp;
@@ -1768,7 +1786,41 @@ static int cjni_config (oconfig_item_t *ci) /* {{{ */
 
   return (0);
 } /* }}} int cjni_config */
+/* }}} */
 
+/* Free the data contained in the `user_data_t' pointer passed to `cjni_read'
+ * and `cjni_write'. In particular, delete the global reference to the Java
+ * object. */
+static void cjni_callback_info_destroy (void *arg) /* {{{ */
+{
+  JNIEnv *jvm_env;
+  cjni_callback_info_t *cbi;
+
+  DEBUG ("java plugin: cjni_callback_info_destroy (arg = %p);", arg);
+
+  if (arg == NULL)
+    return;
+
+  jvm_env = cjni_thread_attach ();
+  if (jvm_env == NULL)
+  {
+    ERROR ("java plugin: cjni_callback_info_destroy: cjni_thread_attach failed.");
+    return;
+  }
+
+  cbi = (cjni_callback_info_t *) arg;
+
+  (*jvm_env)->DeleteGlobalRef (jvm_env, cbi->object);
+
+  cbi->method = NULL;
+  cbi->object = NULL;
+  cbi->class  = NULL;
+  free (cbi);
+
+  cjni_thread_detach ();
+} /* }}} void cjni_callback_info_destroy */
+
+/* Call the CB_TYPE_READ callback pointed to by the `user_data_t' pointer. */
 static int cjni_read (user_data_t *ud) /* {{{ */
 {
   JNIEnv *jvm_env;
@@ -1806,6 +1858,7 @@ static int cjni_read (user_data_t *ud) /* {{{ */
   return (status);
 } /* }}} int cjni_read */
 
+/* Call the CB_TYPE_WRITE callback pointed to by the `user_data_t' pointer. */
 static int cjni_write (const data_set_t *ds, const value_list_t *vl, /* {{{ */
     user_data_t *ud)
 {
@@ -1854,7 +1907,9 @@ static int cjni_write (const data_set_t *ds, const value_list_t *vl, /* {{{ */
   return (status);
 } /* }}} int cjni_write */
 
-
+/* Iterate over `java_classes_list' and create one object of each class. This
+ * will trigger the object's constructors, to the objects can register callback
+ * methods. */
 static int cjni_load_plugins (JNIEnv *jvm_env) /* {{{ */
 {
   size_t i;
@@ -1900,6 +1955,8 @@ static int cjni_load_plugins (JNIEnv *jvm_env) /* {{{ */
   return (0);
 } /* }}} int cjni_load_plugins */
 
+/* Iterate over `java_plugin_configs' and `java_callbacks' and call all
+ * `config' callback methods for which a configuration is available. */
 static int cjni_config_plugins (JNIEnv *jvm_env) /* {{{ */
 {
   int status;
@@ -1948,6 +2005,7 @@ static int cjni_config_plugins (JNIEnv *jvm_env) /* {{{ */
   return (0);
 } /* }}} int cjni_config_plugins */
 
+/* Iterate over `java_callbacks' and call all CB_TYPE_INIT callbacks. */
 static int cjni_init_plugins (JNIEnv *jvm_env) /* {{{ */
 {
   int status;
@@ -1974,6 +2032,7 @@ static int cjni_init_plugins (JNIEnv *jvm_env) /* {{{ */
   return (0);
 } /* }}} int cjni_init_plugins */
 
+/* Iterate over `java_callbacks' and call all CB_TYPE_SHUTDOWN callbacks. */
 static int cjni_shutdown_plugins (JNIEnv *jvm_env) /* {{{ */
 {
   int status;
@@ -2075,15 +2134,17 @@ static int cjni_shutdown (void) /* {{{ */
   return (0);
 } /* }}} int cjni_shutdown */
 
+/* Register ``native'' functions with the JVM. Native functions are C-functions
+ * that can be called by Java code. */
 static int cjni_init_native (JNIEnv *jvm_env) /* {{{ */
 {
   jclass api_class_ptr;
   int status;
 
-  api_class_ptr = (*jvm_env)->FindClass (jvm_env, "org.collectd.api.CollectdAPI");
+  api_class_ptr = (*jvm_env)->FindClass (jvm_env, "org.collectd.api.Collectd");
   if (api_class_ptr == NULL)
   {
-    ERROR ("cjni_init_native: Cannot find API class `org.collectd.api.CollectdAPI'.");
+    ERROR ("cjni_init_native: Cannot find API class `org.collectd.api.Collectd'.");
     return (-1);
   }
 
@@ -2098,6 +2159,8 @@ static int cjni_init_native (JNIEnv *jvm_env) /* {{{ */
   return (0);
 } /* }}} int cjni_init_native */
 
+/* Initialization: Create a JVM, load all configured classes and call their
+ * `config' and `init' callback methods. */
 static int cjni_init (void) /* {{{ */
 {
   JNIEnv *jvm_env;