PAYARA-3061 added javadoc

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/DomainConfigValidator.java

@@ -182,7 +182,8 @@ public boolean isValueValid(Object key, Object value)
     }
 
     /**
-     * @param key
+     * Gets the type of a specified key
+     * @param key the key for the domain config entry
      * @return Returns the accepted datatype for the key. The returned value is
      * the fully qualified class name of the datatype. If the key is invalid or 
      * does not belong to the valid domain config key set, "" is returned.

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/DomainsManager.java

@@ -102,6 +102,11 @@ public void changeMasterPassword(DomainConfig domainConfig)
     public void validateDomain(DomainConfig domainConfig, boolean domainExists)
         throws DomainException;
 
+    /**
+     * Checks that the master password in the config is valid for the keystore
+     * @param config the config to get the password from
+     * @throws DomainException if the password fails to open the keystore
+     */
     public void validateMasterPassword(DomainConfig config) throws DomainException;
 
 }   

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/FileValidator.java

@@ -76,7 +76,7 @@ public class FileValidator extends Validator
      * Constructs a new FileValidator object.
      * @param name The name of the entity that will be validated. This name is
      * used in the error message.
-     * @param constraints The constaint set that will be checked for any given
+     * @param constraints The constraint set that will be checked for any given
      * file during validation.
      */
     public FileValidator(String name, String constraints)
@@ -100,8 +100,9 @@ public String getConstraints()
     /**
      * Sets the current constraint set to the given set if it is a valid 
      * constraint set.
-     * @param constraints
-     * @return 
+     * @param constraints the file permission constraints, may be characters in the form 'drwx'
+     * @return the resulting constraints. If the given constrains was not valid, then the
+     * previous constraints will be returned.
      */
     public String setConstraints(String constraints)
     {

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/InstancesManager.java

@@ -43,6 +43,10 @@
 
 import java.util.Properties;
 
+/**
+ * @deprecated since 184 as there are no known references to it
+ */
+@Deprecated
 public interface InstancesManager
 {    
     /**
@@ -102,7 +106,6 @@ public Process startInstance(String[] interativeOptions, String[] commandLineArg
      * @param commandLineArgs is additional commandline arguments that are to be appended
      *        to the processes commandline when it starts
      * @param envProps properties to be added to System
-     * @return 
      * @throws InstanceException
      */
     public Process startInstance(String[] interativeOptions, String[] commandLineArgs, Properties envProps) 
@@ -117,15 +120,13 @@ public void stopInstance()
 
     /**
      * Lists all the instances.
-     * @return 
      * @throws InstanceException 
      */
     public String[] listInstances() 
         throws InstanceException;
 
     /**
      * Returns status of an instance.
-     * @return 
      * @throws InstanceException
      */
     public int getInstanceStatus()
@@ -142,8 +143,7 @@ public int getInstanceStatus()
 
     /**
      * Tries to stop the instance with the specified timeout.Returns true if success; false if failure
-     * @param timeout  
-     * @return   
+     * @param timeout   
      * @throws InstanceException  
      */    
     public boolean stopInstanceWithinTime(int timeout) 

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/KeystoreManager.java

@@ -263,11 +263,11 @@ private void addSelfSignedCertToKeyStore(final File keystore, final String alias
 
     /**
      * Copy certain certificates from the keystore into the truststore.
-     * @param keyStore
-     * @param trustStore
-     * @param config
-     * @param masterPassword
-     * @throws DomainException
+     * @param keyStore keystore to copy from
+     * @param trustStore the truststore to copy to
+     * @param config the domain's configuration
+     * @param masterPassword the master password for the truststore
+     * @throws DomainException if an error occured
      */
     protected void copyCertificates(File keyStore, File trustStore, DomainConfig config, String masterPassword) throws DomainException {
         try {
@@ -284,7 +284,7 @@ protected void copyCertificates(File keyStore, File trustStore, DomainConfig con
      * 
      * @param trustStore the trust store to copy the certificates to.
      * @param masterPassword the password to the trust store.
-     * @throws RepositoryException
+     * @throws RepositoryException if an error occured a {@link RepositoryException} will wrap the original exception
      */
     protected void copyCertificatesFromJdk(File trustStore, String masterPassword) throws RepositoryException {
         // Gets the location of the JDK trust store.
@@ -631,9 +631,9 @@ public PrivateKey readPlainPKCS8PrivateKey(File keyFile) throws IOException, Inv
      * @param is the input stream containing the private key
      * @param algo the algorithm used for the private key
      * @return the RSA private key
-     * @exception java.io.UncheckedIOException
-     * @throws InvalidKeySpecException
-     * @throws NoSuchAlgorithmException
+     * @exception java.io.UncheckedIOException if there is an error with the {@link InputStream}
+     * @throws InvalidKeySpecException if the key used was not a valid with the algorithm
+     * @throws NoSuchAlgorithmException if no provider exists for the specified algorithm
      */
     public PrivateKey readPlainPKCS8PrivateKey(InputStream is, String algo)
             throws InvalidKeySpecException, NoSuchAlgorithmException {
@@ -739,9 +739,9 @@ protected void changeS1ASAliasPassword(RepositoryConfig config, String storePass
      * It is expected that the key / truststores may not exist. This is
      * due to the fact that the user may have deleted them and wishes to set up their own key/truststore
      *
-     * @param config
-     * @param oldPassword
-     * @param newPassword
+     * @param config the configuration with details of the truststore location and master password
+     * @param oldPassword the previous password
+     * @param newPassword the new password
      * @throws RepositoryException
      */
     protected void changeSSLCertificateDatabasePassword(RepositoryConfig config, String oldPassword, String newPassword)

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/MasterPasswordFileManager.java

@@ -156,9 +156,10 @@ protected void changeMasterPasswordInMasterPasswordFile(RepositoryConfig config,
 
     /**
      * Changes the master password in the master password file
-     * @param saveMasterPassword
-     * @param pwdFile
-     * @param newPassword
+     * @param pwdFile the master password file
+     * @param newPassword the new password
+     * @param saveMasterPassword whether to save the new password. If this is false then
+     * the old file will simply be deleted
      * @throws RepositoryException
      */
     public void changeMasterPasswordInMasterPasswordFile(File pwdFile, String newPassword,

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/PortValidator.java

@@ -55,7 +55,9 @@ public class PortValidator extends Validator {
     private static final StringManager STRING_MANAGER = StringManager.getManager(PortValidator.class);
 
     /** Creates a new instance of PortValidator
-     * @param name */
+     * @param name Name of an entry that is used in case of validation errors.
+     * If the name is null "" is used instead.
+     */
     public PortValidator(String name) {
         super(name, java.lang.Integer.class);
     }

nucleus/admin/server-mgmt/src/main/java/com/sun/enterprise/admin/servermgmt/RepositoryConfig.java

@@ -51,74 +51,76 @@
 import com.sun.enterprise.universal.glassfish.ASenvPropertyReader;
 
 /**
- * This class represents a repository configuration. A repository can be either
- * a domain, a node agent, or a server instance. Configuration specific to each
+ * This class represents a repository configuration. 
+ * <p>
+ * A repository can be either a domain, a node agent, or a server instance. 
+ * Configuration specific to each
  * (DomainConfig, AgentConfig, InstanceConfig) is derived from this class. A
  * repository config consists of the following attributes:
+ * <ol>
+ * <li>repositoryName -- domain or node agent name (e.g. domain1 or agent1)</li>
  *
- * 1)repositoryName -- domain or node agent name (e.g. domain1 or agent1)
+ * <li>repositoryRoot -- the parent directory of the repository (e.g.
+ * $installDir/domains or $installDir/agents)</li>
  *
- * 2)repositoryRoot -- the parent directory of the repository (e.g.
- * $installDir/domains or $installDir/agents)
- *
- * 3)instanceName -- the optional server instance name (e.g. server1)
- *
- * 4)configurationName -- the optional configuration name of the server instance
- * (e.g. default-config).
+ * <li>instanceName -- the optional server instance name (e.g. server1)</li>
  *
+ * <li>configurationName -- the optional configuration name of the server instance
+ * (e.g. default-config).</li>
+ * </ol>
  * Using (repositoryName, repositoryRoot, instanceName, configurationName)
  * syntax. Here are the following permutations:
+ * <ol>
+ * <li>For a domain: (domainRootDirectory, domainName, null, null) e.g.
+ * ("/sun/appserver/domains", "domain1", null, null)</li>
  *
- * 1)For a domain: (domainRootDirectory, domainName, null, null) e.g.
- * ("/sun/appserver/domains", "domain1", null, null)
- *
- * 2)For a node agent: (agentRootDirectory, agentName, "agent", null) e.g
+ * <li>For a node agent: (agentRootDirectory, agentName, "agent", null) e.g
  * ("/sun/appserver/agents", "agent1", "agent", null). Note that the instance
- * name of a node agent is always the literal string "agent".
+ * name of a node agent is always the literal string "agent".</li>
  *
- * 3)For a server instance (agentRootDirectory, agentName, instanceName,
+ * <li>For a server instance (agentRootDirectory, agentName, instanceName,
  * configName) e.g. ("/sun/appserver/agents", "agent1", "server1",
- * "default-config")
- *
+ * "default-config")</li>
+ * </ol>
  * The RepositoryConfig class is an extensible HashMap that can contain any
  * attributes, but also relies on two system properties being set:
+ * <ol>
+ * <li>com.sun.aas.installRoot -- installation root directory stored under the
+ * K_INSTALL_ROOT key.</li>
  *
- * 1)com.sun.aas.installRoot -- installation root directory stored under the
- * K_INSTALL_ROOT key.
- *
- * 2)com.sun.aas.configRoot -- configuration root (for locating asenv.conf)
- * stored under the K_CONFIG_ROOT key.
- *
+ * <li>com.sun.aas.configRoot -- configuration root (for locating asenv.conf)
+ * stored under the K_CONFIG_ROOT key.</li>
+ * </ol>
  * @author kebbs
  * @since August 19, 2003, 1:59 PM
  */
 public class RepositoryConfig extends HashMap<String, Object> {
     public static final String K_INSTALL_ROOT = "install.root";
     public static final String K_CONFIG_ROOT = "config.root";
     public static final String K_REFRESH_CONFIG_CONTEXT = "refresh.cc";
-    //Name of the domain or node agent. Cannot be null.
-    private String _repositoryName;
-    //Root directory where the domain or node agent resides. Cannot be null
-    private String _repositoryRoot;
-    //Name of the server instance. May be null
-    private String _instanceName;
-    //Name of the configuration. May be null
-    private String _configurationName;
+    /** Name of the domain or node agent. Cannot be null. */
+    private String repositoryName;
+    /** Root directory where the domain or node agent resides. Cannot be null */
+    private String repositoryRoot;
+    /** Name of the server instance. May be null */
+    private String instanceName;
+    /** Name of the configuration. May be null */
+    private String configurationName;
 
     /**
      * Creates a new instance of RepositoryConfig The K_INSTALL_ROOT and
      * K_CONFIG_ROOT attributes are implicitly set
-     * @param repositoryName
-     * @param repositoryRoot
-     * @param instanceName
-     * @param configName
+     * @param repositoryName Name of the domain or node agent. Cannot be null.
+     * @param repositoryRoot Root directory where the domain or node agent resides. Cannot be null
+     * @param instanceName Name of the server instance. May be null
+     * @param configName Name of the configuration. May be null
      */
     public RepositoryConfig(String repositoryName, String repositoryRoot, String instanceName,
             String configName) {
-        _instanceName = instanceName;
-        _repositoryName = repositoryName;
-        _repositoryRoot = repositoryRoot;
-        _configurationName = configName;
+        this.instanceName = instanceName;
+        this.repositoryName = repositoryName;
+        this.repositoryRoot = repositoryRoot;
+        configurationName = configName;
         final Map<String, String> envProperties = getEnvProps();
         put(K_INSTALL_ROOT, getFilePath(envProperties.get(SystemPropertyConstants.INSTALL_ROOT_PROPERTY)));
         put(K_CONFIG_ROOT, getFilePath(envProperties.get(SystemPropertyConstants.INSTALL_ROOT_PROPERTY)));
@@ -131,14 +133,29 @@ public RepositoryConfig(String repositoryName, String repositoryRoot, String ins
          */
     }
 
+    /**
+     * Creates a RepositoryConfig for a node agent
+     * @param repositoryName Name of the domain or node agent.
+     * @param repositoryRoot Root directory where the domain or node agent resides.
+     * @param instanceName  Name of the server instance.
+     */
     public RepositoryConfig(String repositoryName, String repositoryRoot, String instanceName) {
         this(repositoryName, repositoryRoot, instanceName, null);
     }
 
+    /**
+     * Creates a RepositoryConfig for a domain
+     * @param repositoryName Name of the domain or node agent.
+     * @param repositoryRoot Root directory where the domain or node agent resides.
+     */
     public RepositoryConfig(String repositoryName, String repositoryRoot) {
         this(repositoryName, repositoryRoot, null);
     }
 
+    /**
+     * Creates a RepositoryConfig based off the instance root property
+     * @see #RepositoryConfig(java.lang.String) 
+     */
     public RepositoryConfig() {
         this(System.getProperty(SystemPropertyConstants.INSTANCE_ROOT_PROPERTY));
     }
@@ -153,19 +170,19 @@ public RepositoryConfig() {
     public RepositoryConfig(String instanceRootString) {
         final File instanceRoot = new File(instanceRootString);
         final File repositoryDir = instanceRoot.getParentFile();
-        _instanceName = instanceRoot.getName();
-        _repositoryName = repositoryDir.getName();
-        _repositoryRoot = FileUtils.makeForwardSlashes(repositoryDir.getParentFile().getAbsolutePath());
-        _configurationName = null;
+        instanceName = instanceRoot.getName();
+        repositoryName = repositoryDir.getName();
+        repositoryRoot = FileUtils.makeForwardSlashes(repositoryDir.getParentFile().getAbsolutePath());
+        configurationName = null;
         final Map<String, String> envProperties = getEnvProps();
         put(K_INSTALL_ROOT, envProperties.get(SystemPropertyConstants.INSTALL_ROOT_PROPERTY));
         put(K_CONFIG_ROOT, getFilePath(envProperties.get(SystemPropertyConstants.CONFIG_ROOT_PROPERTY)));
     }
 
     @Override
     public String toString() {
-        return ("repositoryRoot " + _repositoryRoot + " repositoryName " + _repositoryName
-                + " instanceName " + _instanceName + " configurationName " + _configurationName);
+        return ("repositoryRoot " + repositoryRoot + " repositoryName " + repositoryName
+                + " instanceName " + instanceName + " configurationName " + configurationName);
     }
 
     protected String getFilePath(String propertyName) {
@@ -174,35 +191,35 @@ protected String getFilePath(String propertyName) {
     }
 
     public void setConfigurationName(String configurationName) {
-        _configurationName = configurationName;
+        this.configurationName = configurationName;
     }
 
     public String getConfigurationName() {
-        return _configurationName;
+        return configurationName;
     }
 
     public String getDisplayName() {
         return getRepositoryName();
     }
 
     public void setInstanceName(String instanceName) {
-        _instanceName = instanceName;
+        this.instanceName = instanceName;
     }
 
     public String getInstanceName() {
-        return _instanceName;
+        return instanceName;
     }
 
     public String getRepositoryName() {
-        return _repositoryName;
+        return repositoryName;
     }
 
     protected void setRepositoryRoot(String repositoryRoot) {
-        _repositoryRoot = repositoryRoot;
+        this.repositoryRoot = repositoryRoot;
     }
 
     public String getRepositoryRoot() {
-        return _repositoryRoot;
+        return repositoryRoot;
     }
 
     public String getInstallRoot() {
@@ -214,7 +231,7 @@ public String getConfigRoot() {
     }
 
     public Boolean getRefreshConfigContext() {
-        return ((Boolean) get(K_REFRESH_CONFIG_CONTEXT));
+        return (Boolean) get(K_REFRESH_CONFIG_CONTEXT);
         //this will never be null, because constructor initializes it to false
     }