Patchwork PR: GenerateDocstring

src/com/ibm/security/appscan/altoromutual/model/Account.java

@@ -102,6 +102,17 @@ public static Account[] fromBase64List (String b64accounts){
 		return (accountList.toArray(new Account[accountList.size()]));
 	}
 
+	/**
+	 * Converts an array of Account objects to a Base64 encoded string representation.
+	 * 
+	 * This method takes an array of Account objects and creates a string representation
+	 * where each account's details (accountId, accountName, and balance) are concatenated
+	 * with '~' as a separator between fields and '|' as a separator between accounts.
+	 * The resulting string is then Base64 encoded.
+	 * 
+	 * @param accounts An array of Account objects to be converted
+	 * @return A Base64 encoded string representing the list of accounts
+	 */
 	public static String toBase64List(Account[] accounts){
 
 		StringBuffer accountList = new StringBuffer();

src/com/ibm/security/appscan/altoromutual/model/User.java

@@ -73,6 +73,16 @@ public String getLastName() {
 		return lastName;
 	}
 
+	/**
+	 * Retrieves an array of Account objects for the current user.
+	 * 
+	 * This method attempts to fetch account information from the database
+	 * using the DBUtil.getAccounts() method. If a SQLException occurs during
+	 * the database operation, it prints the stack trace and returns null.
+	 * 
+	 * @return An array of Account objects if successful, or null if an error occurs
+	 * @throws SQLException if a database access error occurs (caught internally)
+	 */
 	public Account[] getAccounts(){
 		try {
 			return DBUtil.getAccounts(username);
@@ -82,6 +92,12 @@ public Account[] getAccounts(){
 		}
 	}
 
+	/**
+	 * Looks up an Account object based on the provided account number.
+	 * 
+	 * @param accountNumber The unique identifier for the account to be retrieved
+	 * @return The Account object matching the given account number, or null if no match is found
+	 */
 	public Account lookupAccount(Long accountNumber) {
 		for (Account account : getAccounts()) {
 			if (account.getAccountId() == accountNumber)
@@ -90,6 +106,14 @@ public Account lookupAccount(Long accountNumber) {
 		return null;
 	}
 
+	/**
+	 * Retrieves the credit card account number for the user.
+	 * 
+	 * This method iterates through the user's accounts and returns the account ID
+	 * of the credit card account if found.
+	 * 
+	 * @return The account ID of the credit card account if found, or -1L if not found.
+	 */
 	public long getCreditCardNumber(){
 		for (Account account: getAccounts()){
 			if (DBUtil.CREDIT_CARD_ACCOUNT_NAME.equals(account.getAccountName()))
@@ -98,6 +122,15 @@ public long getCreditCardNumber(){
 		return -1L;
 	}
 
+	/**
+	 * Retrieves user transactions for specified accounts within a given date range.
+	 * 
+	 * @param startDate The start date of the transaction period (inclusive)
+	 * @param endDate The end date of the transaction period (inclusive)
+	 * @param accounts An array of Account objects to retrieve transactions for
+	 * @return An array of Transaction objects matching the specified criteria
+	 * @throws SQLException If a database access error occurs
+	 */
 	public Transaction[] getUserTransactions(String startDate, String endDate, Account[] accounts) throws SQLException {
 
 		Transaction[] transactions = null;

src/com/ibm/security/appscan/altoromutual/servlet/TransferServlet.java

@@ -48,6 +48,19 @@ protected void doGet(HttpServletRequest req, HttpServletResponse resp)
 	 * @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse response)
 	 */
 
+	/**
+	 * Processes a POST request for transferring funds between accounts.
+	 * 
+	 * This method handles the server-side logic for a fund transfer operation.
+	 * It first checks if the user is logged in, redirecting to the login page if not.
+	 * Then it extracts transfer details from the request parameters, performs the transfer,
+	 * and forwards the result to the transfer.jsp page.
+	 * 
+	 * @param request The HttpServletRequest object containing the client's request data
+	 * @param response The HttpServletResponse object for sending the response to the client
+	 * @throws ServletException If the request cannot be handled
+	 * @throws IOException If an input or output error occurs while the servlet is handling the HTTP request
+	 */
 	protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
 
 

src/com/ibm/security/appscan/altoromutual/util/DBUtil.java

@@ -96,6 +96,17 @@ private DBUtil(){
 		}
 	}
 
+	/**
+	 * Retrieves a database connection, creating one if necessary.
+	 * 
+	 * This method manages a singleton instance of a database connection. It first checks if
+	 * a connection already exists and is open. If not, it attempts to create a new connection
+	 * using either a custom data source (if configured) or the built-in Derby database.
+	 * If the database does not exist, it creates and initializes it.
+	 * 
+	 * @return Connection A valid database connection
+	 * @throws SQLException If there is an error establishing the database connection
+	 */
 	private static Connection getConnection() throws SQLException{
 
 		if (instance == null)
@@ -421,6 +432,17 @@ public static Transaction[] getTransactions(String startDate, String endDate, Ac
 			return transactions.toArray(new Transaction[transactions.size()]); 
 	}
 
+	/**
+	 * Retrieves an array of bank user IDs from the database.
+	 * 
+	 * This method connects to the database, executes a SQL query to select all USER_ID
+	 * values from the PEOPLE table, and returns them as an array of strings.
+	 * 
+	 * @return An array of String containing all user IDs from the database.
+	 *         If an error occurs during database access, an empty array is returned.
+	 * @throws SQLException If a database access error occurs or the SQL query fails.
+	 *         This exception is caught internally and its stack trace is printed.
+	 */
 	public static String[] getBankUsernames() {
 
 		try {
@@ -444,6 +466,17 @@ public static String[] getBankUsernames() {
 		}
 	}
 
+	/**
+	 * Retrieves an Account object from the database based on the provided account number.
+	 * 
+	 * This method establishes a database connection, executes a SQL query to fetch account details,
+	 * and constructs an Account object with the retrieved information. If multiple accounts are found,
+	 * only the first one is returned. If no account is found, null is returned.
+	 * 
+	 * @param accountNo The account number to search for in the database
+	 * @return An Account object containing the account details if found, or null if not found
+	 * @throws SQLException If a database access error occurs or this method is called on a closed connection
+	 */
 	public static Account getAccount(long accountNo) throws SQLException {
 
 		Connection connection = getConnection();
@@ -464,6 +497,14 @@ public static Account getAccount(long accountNo) throws SQLException {
 		return accounts.get(0);
 	}
 
+	/**
+	 * Adds a new account for a given user to the ACCOUNTS database table.
+	 * 
+	 * @param username The user identifier for the account
+	 * @param acctType The type of account to be created
+	 * @return null if the account is successfully added, or an error message if an SQLException occurs
+	 * @throws SQLException if there is an error executing the SQL statement
+	 */
 	public static String addAccount(String username, String acctType) {
 		try {
 			Connection connection = getConnection();
@@ -475,6 +516,16 @@ public static String addAccount(String username, String acctType) {
 		}
 	}
 
+	/**
+	 * Adds a special user to the SPECIAL_CUSTOMERS database table.
+	 * 
+	 * @param username The username of the special user to be added
+	 * @param password The password for the special user
+	 * @param firstname The first name of the special user
+	 * @param lastname The last name of the special user
+	 * @return null if the user is successfully added, or the SQLException message as a String if an error occurs
+	 * @throws SQLException if there is an error executing the SQL statement
+	 */
 	public static String addSpecialUser(String username, String password, String firstname, String lastname) {
 		try {
 			Connection connection = getConnection();
@@ -487,6 +538,19 @@ public static String addSpecialUser(String username, String password, String fir
 		}
 	}
 
+	/**
+	 * Adds a new user to the PEOPLE database table.
+	 * 
+	 * This method inserts a new user record into the PEOPLE table with the provided
+	 * information. The user is assigned the default role of 'user'.
+	 * 
+	 * @param username The unique identifier for the user
+	 * @param password The user's password
+	 * @param firstname The user's first name
+	 * @param lastname The user's last name
+	 * @return null if the user is successfully added, or the error message as a String if an SQLException occurs
+	 * @throws SQLException if there is an error executing the SQL statement
+	 */
 	public static String addUser(String username, String password, String firstname, String lastname) {
 		try {
 			Connection connection = getConnection();
@@ -499,6 +563,14 @@ public static String addUser(String username, String password, String firstname,
 		}
 	}
 
+	/**
+	 * Changes the password for a given user in the database.
+	 * 
+	 * @param username The user ID of the account whose password is to be changed
+	 * @param password The new password to set for the user
+	 * @return null if the password change is successful, or an error message as a String if an SQLException occurs
+	 * @throws SQLException if there is an error executing the SQL statement or connecting to the database
+	 */
 	public static String changePassword(String username, String password) {
 		try {
 			Connection connection = getConnection();
@@ -512,6 +584,16 @@ public static String changePassword(String username, String password) {
 	}
 
 
+	/**
+	 * Stores feedback information in the database.
+	 * 
+	 * @param name The name of the person providing feedback
+	 * @param email The email address of the person providing feedback
+	 * @param subject The subject of the feedback
+	 * @param comments The detailed comments or content of the feedback
+	 * @return The generated ID of the stored feedback entry, or -1 if an error occurred
+	 * @throws SQLException If there is an error executing the SQL statement or accessing the database
+	 */
 	public static long storeFeedback(String name, String email, String subject, String comments) {
 		try{ 
 			Connection connection = getConnection();

src/com/ibm/security/appscan/altoromutual/util/OperationsUtil.java

@@ -15,6 +15,22 @@
 
 public class OperationsUtil {
 
+	/**
+	 * Transfers funds between two accounts via an API call.
+	 * 
+	 * This method processes a fund transfer request between two accounts for an authenticated user.
+	 * It retrieves the user from the request, performs the transfer using a database utility,
+	 * and returns a status message indicating the result of the operation.
+	 * 
+	 * @param request The HttpServletRequest containing the user's authentication information
+	 * @param creditActId The ID of the account to be credited (receiving funds)
+	 * @param debitActId The ID of the account to be debited (sending funds)
+	 * @param amount The amount of funds to transfer
+	 * @return A string message indicating the result of the transfer operation
+	 *         If successful, it includes the amount transferred, account IDs, and timestamp
+	 *         If unsuccessful, it returns an error message with details
+	 * @throws SQLException If a database error occurs during the fund transfer process
+	 */
 	public static String doApiTransfer(HttpServletRequest request, long creditActId, long debitActId,
 			double amount) {
 
@@ -36,6 +52,19 @@ public static String doApiTransfer(HttpServletRequest request, long creditActId,
 	}
 
 
+	/**
+	 * Performs a servlet transfer operation between two bank accounts.
+	 * 
+	 * This method processes a fund transfer request from one account to another.
+	 * It validates the accounts, performs the transfer, and returns a status message.
+	 * The method does not check for available balance before the transfer.
+	 * 
+	 * @param request The HttpServletRequest containing user and session information
+	 * @param creditActId The ID of the destination account to receive the funds
+	 * @param accountIdString The ID or name of the source account to transfer funds from
+	 * @param amount The amount of money to transfer
+	 * @return A string message indicating the result of the transfer operation
+	 */
 	public static String doServletTransfer(HttpServletRequest request, long creditActId, String accountIdString,
 			double amount) {
 
@@ -116,6 +145,15 @@ public static String doServletTransfer(HttpServletRequest request, long creditAc
 		return message;
 	}
 
+	/**
+	 * Sends feedback and optionally stores it in the database.
+	 * 
+	 * @param name The name of the person providing feedback
+	 * @param email The email address of the person providing feedback
+	 * @param subject The subject of the feedback
+	 * @param comments The detailed feedback comments
+	 * @return The ID of the stored feedback as a String if storage is enabled, otherwise null
+	 */
 	public static String sendFeedback(String name, String email,
 			String subject, String comments) {
 
@@ -131,6 +169,13 @@ public static String sendFeedback(String name, String email,
 		return null;
 	}
 
+	/**
+	 * Retrieves a User object based on the access token provided in the HTTP request.
+	 * 
+	 * @param request The HttpServletRequest containing the access token in the Authorization header
+	 * @return User object corresponding to the authenticated user
+	 * @throws SQLException If there's an error accessing the database
+	 */
 	public static User getUser(HttpServletRequest request) throws SQLException{
 
 		String accessToken = request.getHeader("Authorization").replaceAll("Bearer ", "");
@@ -143,6 +188,15 @@ public static User getUser(HttpServletRequest request) throws SQLException{
 
 	}
 
+	/**
+	 * Generates a random string of 7 bytes encoded in UTF-8.
+	 * 
+	 * This method creates a byte array of length 7, fills it with random bytes,
+	 * and then converts it to a UTF-8 encoded string. The resulting string
+	 * may contain non-printable characters.
+	 * 
+	 * @return A randomly generated string of 7 bytes encoded in UTF-8
+	 */
 	public static String makeRandomString() {
 	    byte[] array = new byte[7]; // length is bounded by 7
 	    new Random().nextBytes(array);

src/com/ibm/security/appscan/altoromutual/util/ServletUtil.java

@@ -246,6 +246,12 @@ public static String sanitizeWeb(String data) {
 		return StringEscapeUtils.escapeHtml(data);
 	}
 
+	/**
+	 * Sanitizes HTML input by checking for potential XSS (Cross-Site Scripting) patterns using a regular expression.
+	 * 
+	 * @param input The HTML string to be sanitized
+	 * @return An empty string if the input matches the XSS pattern, otherwise returns the original input
+	 */
 	public static String sanitzieHtmlWithRegex(String input) {
 		if (XSS_REGEXP.matcher(input).matches()) {
 			return "";
@@ -337,6 +343,14 @@ public static void initializeLogFile(ServletContext servletContext) {
 		}
 	}
 
+	/**
+	 * Establishes a session for a given user and creates a cookie with account information.
+	 * 
+	 * @param username The username of the user for whom the session is being established
+	 * @param session The HttpSession object to store user information
+	 * @return A Cookie object containing encoded account information, or null if an error occurs
+	 * @throws SQLException If there's an error retrieving user information from the database
+	 */
 	public static Cookie establishSession(String username, HttpSession session){
 		try{
 			User user = DBUtil.getUserInfo(username);
@@ -352,6 +366,12 @@ public static Cookie establishSession(String username, HttpSession session){
 		}
 	}
 
+	/**
+	 * Checks if a user is logged in based on the session attribute.
+	 * 
+	 * @param request The HttpServletRequest object containing the session information
+	 * @return true if the user is logged in, false otherwise
+	 */
 	static public boolean isLoggedin(HttpServletRequest request){
 		try {
 			// Check user is logged in
@@ -367,6 +387,12 @@ static public boolean isLoggedin(HttpServletRequest request){
 		return true;
 	}
 
+	/**
+	 * Retrieves the User object associated with the current session from the HttpServletRequest.
+	 * 
+	 * @param request The HttpServletRequest object containing the session information
+	 * @return The User object stored in the session, or null if no user is associated with the session
+	 */
 	static public User getUser(HttpServletRequest request){
 		User user = (User)request.getSession().getAttribute(ServletUtil.SESSION_ATTR_USER);
 		return user;