From 4f0e8c4868a5a4a9e7b1958024ca47777cfc91d3 Mon Sep 17 00:00:00 2001 From: IllianiCBT Date: Mon, 16 Sep 2024 13:44:59 -0500 Subject: [PATCH 1/3] Added Post-Name Change Compatibility Handlers, Added JavaDocs to PersonnelRole.java Added compatibility handlers for the roles that hand their names changed by the name change project. Added JavaDocs for better code documentation and readability. Added a Nullable and Deprecated annotation. --- .../personnel/enums/PersonnelRole.java | 278 ++++++++++++++---- 1 file changed, 227 insertions(+), 51 deletions(-) diff --git a/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java b/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java index 64a5e663a2..5a5142fa84 100644 --- a/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java +++ b/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020-2022 - The MegaMek Team. All Rights Reserved. + * Copyright (c) 2020-2024 - The MegaMek Team. All Rights Reserved. * * This file is part of MekHQ. * @@ -18,17 +18,26 @@ */ package mekhq.campaign.personnel.enums; +import megamek.common.annotations.Nullable; +import megamek.logging.MMLogger; +import mekhq.MekHQ; + import java.awt.event.KeyEvent; import java.util.List; import java.util.ResourceBundle; import java.util.stream.Collectors; import java.util.stream.Stream; -import megamek.logging.MMLogger; -import mekhq.MekHQ; - +/** + * The PersonnelRole enum represents various roles a person can have. + * Each role is associated with a name, an optional clan name, and a mnemonic key event. + * These roles can be used to classify personnel. + */ public enum PersonnelRole { // region Enum Declarations + /** + * Individual roles with corresponding name texts and mnemonics. + */ MEKWARRIOR("PersonnelRole.MEKWARRIOR.text", KeyEvent.VK_M), LAM_PILOT("PersonnelRole.LAM_PILOT.text", KeyEvent.VK_UNDEFINED), GROUND_VEHICLE_DRIVER("PersonnelRole.GROUND_VEHICLE_DRIVER.text", KeyEvent.VK_V), @@ -67,11 +76,24 @@ public enum PersonnelRole { // endregion Variable Declarations // region Constructors + /** + * Constructs a new PersonnelRole with the given name and mnemonic. + * + * @param name the name of the personnel role + * @param mnemonic the mnemonic of the personnel role + */ PersonnelRole(final String name, final int mnemonic) { this(name, null, mnemonic); } - PersonnelRole(final String name, final String clanName, final int mnemonic) { + /** + * Main constructor that initializes the role with name, clanName, and mnemonic. + * ClanName is optional and defaults to name if {@code null}. + * @param name the name of the role. + * @param clanName the clan name of the role can be {@code null}. + * @param mnemonic the mnemonic associated with the role. + */ + PersonnelRole(final String name, @Nullable final String clanName, final int mnemonic) { final ResourceBundle resources = ResourceBundle.getBundle("mekhq.resources.Personnel", MekHQ.getMHQOptions().getLocale()); this.name = resources.getString(name); @@ -91,211 +113,336 @@ public int getMnemonic() { // endregion Getters // region Boolean Comparison Methods + /** + * @return {@code true} if the personnel has the Mek Warrior role, {@code false} otherwise. + */ public boolean isMekWarrior() { return this == MEKWARRIOR; } - + /** + * @return {@code true} if the personnel has the LAM Pilot role, {@code false} otherwise. + */ public boolean isLAMPilot() { return this == LAM_PILOT; } - + /** + * @return {@code true} if the personnel has the Ground Vehicle Driver role, {@code false} + * otherwise. + */ public boolean isGroundVehicleDriver() { return this == GROUND_VEHICLE_DRIVER; } + /** + * @return {@code true} if the personnel has the Naval Vehicle Driver role, {@code false} + * otherwise. + */ public boolean isNavalVehicleDriver() { return this == NAVAL_VEHICLE_DRIVER; } + /** + * @return {@code true} if the personnel has the VTOL Pilot role, {@code false} otherwise. + */ public boolean isVTOLPilot() { return this == VTOL_PILOT; } + /** + * @return {@code true} if the personnel has the Vehicle Gunner role, {@code false} otherwise. + */ public boolean isVehicleGunner() { return this == VEHICLE_GUNNER; } + /** + * @return {@code true} if the personnel has the Vehicle Crew role, {@code false} otherwise. + */ public boolean isVehicleCrew() { return this == VEHICLE_CREW; } + /** + * @return {@code true} if the personnel has the Aerospace Pilot role, {@code false} otherwise. + */ public boolean isAerospacePilot() { return this == AEROSPACE_PILOT; } + /** + * @return {@code true} if the personnel has the Conventional Aircraft Pilot role, {@code false} + * otherwise. + */ public boolean isConventionalAircraftPilot() { return this == CONVENTIONAL_AIRCRAFT_PILOT; } + /** + * @return {@code true} if the personnel has the ProtoMek Pilot role, {@code false} otherwise. + */ public boolean isProtoMekPilot() { return this == PROTOMEK_PILOT; } + /** + * @return {@code true} if the personnel has the Battle Armor Pilot role, {@code false} otherwise. + */ public boolean isBattleArmour() { return this == BATTLE_ARMOUR; } + /** + * @return {@code true} if the personnel has the Soldier role, {@code false} otherwise. + */ public boolean isSoldier() { return this == SOLDIER; } + /** + * @return {@code true} if the personnel has the Vessel Pilot role, {@code false} otherwise. + */ public boolean isVesselPilot() { return this == VESSEL_PILOT; } + /** + * @return {@code true} if the personnel has the Vessel Gunner role, {@code false} otherwise. + */ public boolean isVesselGunner() { return this == VESSEL_GUNNER; } + /** + * @return {@code true} if the personnel has the Vessel Crew role, {@code false} otherwise. + */ public boolean isVesselCrew() { return this == VESSEL_CREW; } + /** + * @return {@code true} if the personnel has the Vessel Navigator role, {@code false} otherwise. + */ public boolean isVesselNavigator() { return this == VESSEL_NAVIGATOR; } + /** + * @return {@code true} if the personnel has the MekTech role, {@code false} otherwise. + */ public boolean isMekTech() { return this == MEK_TECH; } + /** + * @return {@code true} if the personnel has the Mechanic role, {@code false} otherwise. + */ public boolean isMechanic() { return this == MECHANIC; } + /** + * @return {@code true} if the personnel has the AeroTek role, {@code false} otherwise. + */ public boolean isAeroTek() { return this == AERO_TEK; } + /** + * @return {@code true} if the personnel has the Battle Armor Tech role, {@code false} otherwise. + */ public boolean isBATech() { return this == BA_TECH; } + /** + * @return {@code true} if the personnel has the Astech role, {@code false} otherwise. + */ public boolean isAstech() { return this == ASTECH; } + /** + * @return {@code true} if the personnel has the Doctor role, {@code false} otherwise. + */ public boolean isDoctor() { return this == DOCTOR; } + /** + * @return {@code true} if the personnel has the Medic role, {@code false} otherwise. + */ public boolean isMedic() { return this == MEDIC; } + /** + * @return {@code true} if the personnel has the Admin/Command role, {@code false} otherwise. + */ public boolean isAdministratorCommand() { return this == ADMINISTRATOR_COMMAND; } + /** + * @return {@code true} if the personnel has the Admin/Logistics role, {@code false} otherwise. + */ public boolean isAdministratorLogistics() { return this == ADMINISTRATOR_LOGISTICS; } + /** + * @return {@code true} if the personnel has the Admin/Transport role, {@code false} otherwise. + */ public boolean isAdministratorTransport() { return this == ADMINISTRATOR_TRANSPORT; } + /** + * @return {@code true} if the personnel has the Admin/HR role, {@code false} otherwise. + */ public boolean isAdministratorHR() { return this == ADMINISTRATOR_HR; } + /** + * @return {@code true} if the personnel has the Dependent role, {@code false} otherwise. + */ public boolean isDependent() { return this == DEPENDENT; } + /** + * @return {@code true} if the personnel has the None role, {@code false} otherwise. + */ public boolean isNone() { return this == NONE; } + /** + * @return {@code true} if the character has a combat role, {@code true} otherwise. + */ public boolean isCombat() { - switch (this) { - case MEKWARRIOR: - case LAM_PILOT: - case GROUND_VEHICLE_DRIVER: - case NAVAL_VEHICLE_DRIVER: - case VTOL_PILOT: - case VEHICLE_GUNNER: - case VEHICLE_CREW: - case AEROSPACE_PILOT: - case CONVENTIONAL_AIRCRAFT_PILOT: - case PROTOMEK_PILOT: - case BATTLE_ARMOUR: - case SOLDIER: - case VESSEL_PILOT: - case VESSEL_GUNNER: - case VESSEL_CREW: - case VESSEL_NAVIGATOR: - return true; - case MEK_TECH: - case MECHANIC: - case AERO_TEK: - case BA_TECH: - case ASTECH: - case DOCTOR: - case MEDIC: - case ADMINISTRATOR_COMMAND: - case ADMINISTRATOR_LOGISTICS: - case ADMINISTRATOR_TRANSPORT: - case ADMINISTRATOR_HR: - case DEPENDENT: - case NONE: - default: - return false; - } + return switch (this) { + case MEKWARRIOR, LAM_PILOT, GROUND_VEHICLE_DRIVER, NAVAL_VEHICLE_DRIVER, VTOL_PILOT, + VEHICLE_GUNNER, VEHICLE_CREW, AEROSPACE_PILOT, CONVENTIONAL_AIRCRAFT_PILOT, + PROTOMEK_PILOT, BATTLE_ARMOUR, SOLDIER, VESSEL_PILOT, VESSEL_GUNNER, VESSEL_CREW, + VESSEL_NAVIGATOR -> true; + default -> false; + }; } + /** + * @return {@code true} if the character is a MekWarrior or a LAM Pilot, {@code false} otherwise. + */ public boolean isMekWarriorGrouping() { return isMekWarrior() || isLAMPilot(); } + /** + * @return {@code true} if the character is an Aerospace Pilot or a LAM Pilot, {@code false} + * otherwise. + */ public boolean isAerospaceGrouping() { return isLAMPilot() || isAerospacePilot(); } + /** + * Deprecated in favor of {@code isConventionalAircraftPilot()} + */ + @Deprecated public boolean isConventionalAirGrouping() { return isConventionalAircraftPilot(); } + /** + * @return {@code true} if the character is assigned to the Ground Vehicle Driver, Vehicle Gunner, + * or the Vehicle Crew role, {@code false} otherwise. + */ public boolean isGroundVehicleCrew() { return isGroundVehicleDriver() || isVehicleGunner() || isVehicleCrew(); } + /** + * @return {@code true} if the character is assigned to the Naval Vehicle Driver, Vehicle Gunner, + * or the Vehicle Crew role, {@code false} otherwise. + */ public boolean isNavalVehicleCrew() { return isNavalVehicleDriver() || isVehicleGunner() || isVehicleCrew(); } + /** + * @return {@code true} if the character is assigned to the VTOL Pilot, Vehicle Gunner, or the + * Vehicle Crew role, {@code false} otherwise. + */ public boolean isVTOLCrew() { return isVTOLPilot() || isVehicleGunner() || isVehicleCrew(); } + /** + * @return {@code true} if the character is assigned to the Ground Vehicle Crew, + * Naval Vehicle Crew, or the VTOL Pilot role, {@code false} otherwise. + */ public boolean isVehicleCrewMember() { return isGroundVehicleCrew() || isNavalVehicleDriver() || isVTOLPilot(); } + /** + * @return {@code true} if the character is assigned to the Soldier, or the Battle Armor role, + * {@code false} otherwise. + */ public boolean isSoldierOrBattleArmour() { return isSoldier() || isBattleArmour(); } + /** + * @return {@code true} if the character is assigned to the Vessel Pilot, Vessel Gunner, + * Vessel Crew, or the Vessel Navigator role, {@code false} otherwise. + */ public boolean isVesselCrewMember() { return isVesselPilot() || isVesselGunner() || isVesselCrew() || isVesselNavigator(); } + /** + * @return {@code true} if the character is assigned to a support role, excluding civilian roles, + * {@code false} otherwise. + */ public boolean isSupport() { return isSupport(false); } + /** + * @return {@code true} if the character is assigned to a support role, {@code false} otherwise. + * + * @param excludeCivilian whether to exclude civilian roles + */ public boolean isSupport(final boolean excludeCivilian) { return !isCombat() && (!excludeCivilian || !isCivilian()); } + /** + * Checks whether a character is assigned to a technician role. + * If checking secondary roles, {@code isTechSecondary} should be used. + * + * @return {@code true} if the character is assigned to a technician role, {@code false} + * otherwise. + */ public boolean isTech() { return isMekTech() || isMechanic() || isAeroTek() || isBATech() || isVesselCrew(); } + /** + * Checks whether a character is assigned to a technician role. + * If checking primary roles, {@code isTech} should be used. + * + * @return {@code true} if the character is assigned to a technician role, {@code false} + * otherwise. + */ public boolean isTechSecondary() { return isMekTech() || isMechanic() || isAeroTek() || isBATech(); } + /** + * @return {@code true} if the character is assigned to a medical role, {@code false} otherwise. + */ public boolean isMedicalStaff() { return isDoctor() || isMedic(); } @@ -307,11 +454,19 @@ public boolean isAssistant() { return isAstech() || isMedic(); } + /** + * @return {@code true} if the character is assigned to an Administrative role, {@code false} + * otherwise. + */ public boolean isAdministrator() { return isAdministratorCommand() || isAdministratorLogistics() || isAdministratorTransport() || isAdministratorHR(); } + /** + * @return {@code true} if the character's assigned role is Dependent or None, {@code false} + * otherwise. + */ public boolean isCivilian() { return isDependent() || isNone(); } @@ -375,17 +530,22 @@ public static int getCivilianCount() { } // endregion Static Methods + /** + * Parses a string representation of a {@link PersonnelRole} and returns the corresponding enum + * value. + * + * @param personnelRole the string representation of the {@link PersonnelRole} + * @return the corresponding {@link PersonnelRole} enum value, or {@code NONE} if parsing fails + */ // region File I/O - public static PersonnelRole parseFromString(final String text) { + public static PersonnelRole parseFromString(final String personnelRole) { try { - return valueOf(text); - } catch (Exception ignored) { - - } + return valueOf(personnelRole); + } catch (Exception ignored) {} // Magic Number Save Format try { - switch (Integer.parseInt(text)) { + switch (Integer.parseInt(personnelRole)) { case 0: return NONE; case 1: @@ -445,19 +605,35 @@ public static PersonnelRole parseFromString(final String text) { default: break; } - } catch (Exception ignored) { + } catch (Exception ignored) {} + // <50.1 compatibility + switch (personnelRole) { + case "MECHWARRIOR" -> { + return MEKWARRIOR; + } + case "PROTOMECH_PILOT" -> { + return PROTOMEK_PILOT; + } + case "MECH_TECH" -> { + return MEK_TECH; + } + case "AERO_TECH" -> { + return AERO_TEK; + } + default -> {} } + // Error report, if parsing fails. MMLogger.create(PersonnelRole.class) - .error("Unable to parse " + text + " into a PersonnelRole. Returning NONE."); + .error("Unable to parse {} into a PersonnelRole. Returning NONE.", personnelRole); return NONE; } // endregion File I/O /** - * This method is not recommend to be used in MekHQ, but is provided for - * non-specified utilization + * This method is not recommended to be used in MekHQ, but is provided for non-specified + * utilization * * @return the base name of this role, without applying any overrides */ From 752cc96576594886f1ceeeb2500072809267a2c8 Mon Sep 17 00:00:00 2001 From: IllianiCBT Date: Tue, 17 Sep 2024 14:17:00 -0500 Subject: [PATCH 2/3] Rolled back error logging in PersonnelRole Replaced string formatting with concatenation for error logging in `PersonnelRole`. This change was necessary due to the absence of support for string formatting in the current logging mechanism. --- MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java b/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java index 5a5142fa84..a9f9b9c537 100644 --- a/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java +++ b/MekHQ/src/mekhq/campaign/personnel/enums/PersonnelRole.java @@ -625,8 +625,10 @@ public static PersonnelRole parseFromString(final String personnelRole) { } // Error report, if parsing fails. + // Ignore IDEA's suggestion of concatenating the error log, as this functionality doesn't + // exist within MMLogger MMLogger.create(PersonnelRole.class) - .error("Unable to parse {} into a PersonnelRole. Returning NONE.", personnelRole); + .error("Unable to parse " + personnelRole + " into a PersonnelRole. Returning NONE."); return NONE; } // endregion File I/O From b9e56d1ce4fa7fa8ec8ac7aaab9c05dff3e4c584 Mon Sep 17 00:00:00 2001 From: Daniel L- <103902653+IllianiCBT@users.noreply.github.com> Date: Tue, 17 Sep 2024 17:43:33 -0500 Subject: [PATCH 3/3] Update history.txt --- MekHQ/docs/history.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/MekHQ/docs/history.txt b/MekHQ/docs/history.txt index 440d13b0cd..38f7d802e5 100644 --- a/MekHQ/docs/history.txt +++ b/MekHQ/docs/history.txt @@ -30,6 +30,7 @@ MEKHQ VERSION HISTORY: + PR #4843: Added Post-Name Change Compatibility Handlers, Added JavaDocs to Phenotype.java + PR #4846: Restored Missing Portrait Folders + PR #4847: Added Post-Name Change Compatibility Handlers to SkillType.java ++ FIX #4833: Added Post-Name Change Compatibility Handlers, Added JavaDocs to PersonnelRole.java 0.50.0 (2024-09-01 2000 UTC) (THIS MARKS THE START OF JAVA 17 AS THE MINIMUM REQUIRED) + PR #4332: CI Updates for windows build and normalizing