diff --git a/tamguo-common/src/main/java/com/tamguo/common/utils/LogHandler.java b/tamguo-common/src/main/java/com/tamguo/common/utils/LogHandler.java index 5fe8d8e..6cec9f7 100644 --- a/tamguo-common/src/main/java/com/tamguo/common/utils/LogHandler.java +++ b/tamguo-common/src/main/java/com/tamguo/common/utils/LogHandler.java @@ -1,21 +1,37 @@ package com.tamguo.common.utils; +// LogHandler接口定义了一套统一的日志处理方法规范，旨在为不同的日志级别（如信息、错误、调试、警告等）提供一致的调用方式，方便具体的日志实现类去实现这些方法，以满足在各种场景下记录相应级别日志的需求。 public interface LogHandler { - + + // 用于记录信息级别（INFO）的日志，该方法接收要记录的日志消息内容以及调用类的全限定名作为参数。 + // 通常在程序正常运行过程中，需要记录一些关键业务操作、流程步骤等信息时使用，方便后续查看程序执行的轨迹和状态，例如记录用户登录成功、数据查询完成等情况。 public void info(String msg, String fqnOfCallingClass); - + + // 同样用于记录信息级别（INFO）的日志，但此方法还关联了一个表示异常情况的Throwable对象，除了记录基本的日志消息内容外， + // 还可以在出现异常但不影响整体业务流程继续执行的情况下，将异常相关信息一并记录下来，方便排查可能存在的隐患或者了解一些特殊情况，例如记录某个数据获取操作虽然成功了，但是过程中出现了可忽略的小异常等场景。 public void info(String msg, Throwable t, String fqnOfCallingClass); - + + // 用于记录错误级别（ERROR）的日志，接收日志消息内容和调用类的全限定名作为参数，主要用于在程序出现严重错误，影响业务正常执行时， + // 记录详细的错误信息，比如数据库连接失败、关键业务逻辑执行出错等情况，便于开发人员快速定位和解决问题，保障系统的稳定性。 public void error(String msg, String fqnOfCallingClass); + // 记录错误级别（ERROR）的日志，同时关联异常对象，在出现错误且需要详细的异常堆栈信息来辅助排查问题时使用，例如出现未捕获的运行时异常、业务规则验证不通过导致的严重错误等场景， + // 通过记录异常对象包含的详细堆栈信息、异常类型及消息等，可以更精准地分析错误产生的根源，进而修复问题。 public void error(String msg, Throwable t, String fqnOfCallingClass); - + + // 用于记录调试级别（DEBUG）的日志，接收日志消息内容和调用类的全限定名作为参数，在开发和调试阶段，开发人员可以通过此方法输出一些关键变量的值、代码执行路径等详细的调试信息， + // 帮助理解程序的执行逻辑，查找潜在的逻辑错误或者验证代码是否按照预期执行，通常在非生产环境下使用较多，方便调试代码。 public void debug(String msg, String fqnOfCallingClass); - + + // 记录调试级别（DEBUG）的日志并关联异常对象，在调试过程中如果遇到异常情况，既可以输出自定义的调试消息，又能同时展示异常的详细信息， + // 方便开发人员快速定位是在何种调试场景下出现的异常，对于复杂的业务逻辑调试和问题排查很有帮助。 public void debug(String msg, Throwable t, String fqnOfCallingClass); - + + // 用于记录警告级别（WARNING）的日志，接收日志消息内容和调用类的全限定名作为参数，主要用于记录一些可能会导致问题，但当前还未影响业务正常运行的情况， + // 比如配置文件中的某个参数值不太合理、即将达到系统资源阈值等场景，通过记录警告信息提醒开发人员关注相关情况，提前采取措施避免问题恶化。 public void warning(String msg, String fqnOfCallingClass); - + + // 记录警告级别（WARNING）的日志并关联异常对象，在出现警告情况且存在相关异常信息需要一并记录时使用，例如读取外部资源时遇到了可恢复的异常，虽然当前不影响主要业务，但值得记录下来作为后续优化或者排查潜在问题的参考。 public void warning(String msg, Throwable t, String fqnOfCallingClass); - -} + +} \ No newline at end of file diff --git a/tamguo-common/src/main/java/com/tamguo/common/utils/Result.java b/tamguo-common/src/main/java/com/tamguo/common/utils/Result.java index 850b79d..29bba8c 100644 --- a/tamguo-common/src/main/java/com/tamguo/common/utils/Result.java +++ b/tamguo-common/src/main/java/com/tamguo/common/utils/Result.java @@ -5,23 +5,32 @@ import java.util.HashMap; import java.util.List; import java.util.Map; +// Result类用于封装操作结果相关的信息，包括操作的状态码、具体的结果数据以及对应的提示消息等，实现了Serializable接口，意味着该类的对象可以被序列化，方便在网络传输、持久化存储等场景下使用。 public class Result implements Serializable { + // 序列化版本号，用于在序列化和反序列化过程中确保类结构的兼容性，当类的结构发生变化（如新增、删除字段等）时，可能需要更新该版本号，这里已经给定了一个初始值。 private static final long serialVersionUID = -1651614836984397356L; + // 用于存储操作结果的状态码，不同的数值代表不同的操作结果状态，例如成功、失败等情况，方便调用者根据状态码快速判断操作是否成功以及进行相应的后续处理。 private int code; + // 用于存放具体的操作结果数据，可以是各种类型的对象，比如查询数据库返回的实体对象列表、单个对象，或者是经过业务逻辑处理后的其他相关数据等。 private Object result; + // 用于存储与操作结果相关的提示消息，例如操作成功时可以为空字符串，操作失败时则存放具体的失败原因描述信息，便于向调用者反馈操作的详细情况。 private String message; + // 定义表示成功的状态码常量，方便在代码中统一使用，通常在操作顺利完成、符合预期的情况下使用该状态码来表示成功状态，值为0。 public static final int SUCCESS_CODE = 0; + // 定义表示失败的状态码常量，用于在操作出现错误、未达到预期结果时标记失败状态，值为1，便于在代码中清晰地标识操作失败的情况。 public static final int FAIL_CODE = 1; + // 私有构造函数，将构造函数私有化，阻止外部直接通过`new`关键字创建`Result`对象，强制使用类中提供的静态方法来获取`Result`实例，这样可以更好地控制对象的创建和初始化过程，确保对象状态的一致性。 private Result() { } + // 私有构造函数，用于在类内部根据传入的状态码、结果数据以及消息来创建`Result`对象，外部无法直接调用，同样是为了保证对象创建的规范性和可控性。 private Result(int code, Object result, String message) { this.code = code; this.result = result; @@ -29,48 +38,114 @@ public class Result implements Serializable { } /** - * 成功响应 - * - * @param result - * @return + * 创建表示成功的操作结果对象，返回包含具体结果数据的`Result`实例，状态码会被设置为成功状态码（`SUCCESS_CODE`），消息默认为空字符串。 + * 通常在业务操作顺利完成，需要将结果返回给调用者时使用该方法来构造成功的响应对象。 + * + * @param result 具体的操作结果数据，可以是各种类型的对象，例如查询到的用户信息列表、单个用户对象等，将被赋值到`Result`对象的`result`字段中。 + * @return 表示成功的`Result`对象，其状态码为`SUCCESS_CODE`，包含传入的结果数据以及空的消息字符串。 */ public static Result successResult(Object result) { return result(SUCCESS_CODE, result, ""); } + /** + * 重载的`successResult`方法，用于创建表示成功的操作结果对象，该方法主要用于处理分页相关的数据结构返回情况，接收分页数据（记录列表、总记录数、每页行数）以及可选的用户自定义数据作为参数， + * 内部会进一步调用`resultOfList`方法来构建包含这些信息的`Map`对象，然后将该`Map`对象作为结果数据封装到`Result`对象中返回，表示操作成功并附带相关分页及自定义数据信息。 + * 这里调用了另一个`successResult`的重载方法，默认将用户自定义数据参数设为`null`进行传递。 + * + * @param records 分页查询得到的记录列表，通常是一个包含多个实体对象的集合，例如查询到的多条用户信息记录列表等。 + * @param recordSum 总的记录数，即满足查询条件的所有记录的数量，用于表示数据总量情况，方便前端进行分页导航等相关操作。 + * @param rowsOfPage 每页显示的记录行数，用于确定分页的大小，告诉前端每页应该展示多少条数据。 + * @return 表示成功的`Result`对象，其状态码为`SUCCESS_CODE`，包含整合了分页及相关数据的`Map`类型结果数据以及空的消息字符串。 + */ public static Result successResult(Object records, Long recordSum, Long rowsOfPage) { return successResult(records, recordSum, rowsOfPage, null); } + /** + * 创建表示成功的操作结果对象，用于处理分页相关的数据结构返回情况，并可附带用户自定义数据。 + * 首先调用`resultOfList`方法根据传入的记录列表、总记录数、每页行数以及用户自定义数据构建一个`Map`对象，该`Map`对象整合了这些相关信息， + * 然后将这个`Map`对象作为结果数据通过调用`successResult(Object result)`方法封装到`Result`对象中返回，表示操作成功并附带详细的分页及自定义数据信息。 + * + * @param records 分页查询得到的记录列表，通常是一个包含多个实体对象的集合，例如查询到的多条用户信息记录列表等。 + * @param recordSum 总的记录数，即满足查询条件的所有记录的数量，用于表示数据总量情况，方便前端进行分页导航等相关操作。 + * @param rowsOfPage 每页显示的记录行数，用于确定分页的大小，告诉前端每页应该展示多少条数据。 + * @param userData 用户自定义的数据，可以是任何与业务相关的额外信息，例如用户权限信息、相关配置参数等，会被添加到返回的结果`Map`中，方便前端或其他调用者获取使用。 + * @return 表示成功的`Result`对象，其状态码为`SUCCESS_CODE`，包含整合了分页及相关数据的`Map`类型结果数据以及空的消息字符串。 + */ public static Result successResult(Object records, Long recordSum, Long rowsOfPage, Object userData) { Map result = resultOfList(records, recordSum, rowsOfPage, userData); return successResult(result); } + /** + * 创建用于存放分页相关信息的`Map`对象，该方法主要是对`resultOfList`另一个重载方法的简单调用，默认将用户自定义数据参数设为`null`，用于构建包含记录列表、总记录数以及每页行数等基本分页信息的`Map`对象， + * 方便后续作为结果数据的一部分进行传递和处理，例如在分页查询结果返回时整合相关数据使用。 + * + * @param records 分页查询得到的记录列表，通常是一个包含多个实体对象的集合，例如查询到的多条用户信息记录列表等。 + * @param recordSum 总的记录数，即满足查询条件的所有记录的数量，用于表示数据总量情况，方便前端进行分页导航等相关操作。 + * @param rowsOfPage 每页显示的记录行数，用于确定分页的大小，告诉前端每页应该展示多少条数据。 + * @return 包含分页相关信息的`Map`对象，其中键值对分别为 "rows"（对应记录列表）、"records"（对应总记录数）、"total"（对应每页行数）等，方便后续使用和扩展。 + */ public static Map resultOfList(Object records, Long recordSum, Long rowsOfPage) { return resultOfList(records, recordSum, rowsOfPage, null); } + /** + * 创建用于存放分页相关信息以及可选的用户自定义数据的`Map`对象。 + * 首先创建一个新的`HashMap`实例，然后向其中添加以下键值对信息： + * - "rows"：对应传入的记录列表（`Obj`参数），存放分页查询得到的具体记录数据集合，方便前端展示具体的分页内容。 + * - "records"：对应传入的总记录数（`records`参数），用于表示满足查询条件的所有记录的数量，便于前端进行分页导航等操作，例如计算总页数等。 + * - "total"：对应传入的每页行数（`rowsOfPage`参数），用于明确分页的大小，让前端知道每页应该展示多少条数据。 + * - 如果传入的用户自定义数据（`userData`参数）不为`null`，则添加 "userdata" 键值对，将用户自定义数据存入`Map`中，方便传递额外的业务相关信息。 + * 最后返回构建好的包含分页及相关信息的`Map`对象，可用于作为结果数据进行传递、展示等操作。 + * + * @param Obj 分页查询得到的记录列表，通常是一个包含多个实体对象的集合，例如查询到的多条用户信息记录列表等，对应`Map`中的 "rows" 键值。 + * @param records 总的记录数，即满足查询条件的所有记录的数量，用于表示数据总量情况，方便前端进行分页导航等相关操作，对应`Map`中的 "records" 键。 + * @param rowsOfPage 每页显示的记录行数，用于确定分页的大小，告诉前端每页应该展示多少条数据，对应`Map`中的 "total" 键。 + * @param userData 用户自定义的数据，可以是任何与业务相关的额外信息，例如用户权限信息、相关配置参数等，若不为`null`则对应`Map`中的 "userdata" 键。 + * @return 包含分页相关信息以及可选用户自定义数据的`Map`对象，方便作为结果数据在不同层之间传递和处理。 + */ public static Map resultOfList(Object Obj, Long records, Long rowsOfPage, Object userData) { Map result = new HashMap(); result.put("rows", Obj); result.put("records", records); result.put("total", rowsOfPage); - if (null != userData) { + if (null!= userData) { result.put("userdata", userData); } ; return result; } + /** + * 创建用于符合`jqGrid`组件（一种常用的前端表格插件）要求的分页结果数据`Map`对象。 + * 首先创建一个新的`HashMap`实例，然后向其中添加以下键值对信息： + * - "list"：对应传入的列表数据（`list`参数），存放具体的记录数据集合，用于在`jqGrid`表格中展示实际的内容。 + * - "count"：对应传入的总记录数（`totalCount`参数），用于表示满足查询条件的所有记录的数量，便于`jqGrid`进行分页导航等相关操作，例如计算总页数等。 + * - "next"：根据当前页码（`currPage`参数）和总页数（`totalPage`参数）来确定下一页的页码，如果当前页已经是最后一页，则下一页页码等于当前页码，否则为当前页码加1，用于`jqGrid`的分页导航中“下一页”按钮的逻辑判断。 + * - "prev"：同样根据当前页码和总页数来确定上一页的页码，如果当前页是第一页，则上一页页码为1，否则为当前页码减1，用于`jqGrid`的分页导航中“上一页”按钮的逻辑判断。 + * - "first"：固定值为1，表示第一页的页码，用于`jqGrid`的分页导航中“首页”按钮的逻辑判断。 + * - "last"：对应传入的总页数（`totalPage`参数），表示最后一页的页码，用于`jqGrid`的分页导航中“尾页”按钮的逻辑判断。 + * - "pageSize"：对应传入的每页显示的记录数（`pageSize`参数），用于明确分页的大小，告诉`jqGrid`表格每页应该展示多少条数据。 + * - "pageNo"：对应传入的当前页码（`currPage`参数），用于表示当前所处的页码位置，方便`jqGrid`进行分页相关的显示和操作。 + * 最后返回构建好的包含符合`jqGrid`分页要求的所有信息的`Map`对象，方便与前端`jqGrid`组件进行数据交互，展示分页查询结果。 + * + * @param list 分页查询得到的记录列表，通常是一个包含多个实体对象的集合，例如查询到的多条用户信息记录列表等，用于在`jqGrid`表格中展示具体的数据内容。 + * @param totalCount 总的记录数，即满足查询条件的所有记录的数量，用于表示数据总量情况，方便`jqGrid`进行分页导航等相关操作，例如计算总页数等。 + * @param pageSize 每页显示的记录数，用于确定分页的大小，告诉`jqGrid`表格每页应该展示多少条数据。 + * @param currPage 当前页码，用于表示当前所处的页码位置，方便`jqGrid`进行分页相关的显示和操作。 + * @param totalPage 总页数，根据总记录数和每页记录数计算得出，用于`jqGrid`的分页导航中判断是否处于最后一页等相关操作。 + * @return 包含符合`jqGrid`分页要求的所有信息的`Map`对象，用于与前端`jqGrid`组件进行数据交互，展示分页查询结果。 + */ public static Map jqGridResult(List list, long totalCount, int pageSize, int currPage, - int totalPage) { + int totalPage) { Map result = new HashMap(); result.put("list", list); result.put("count", totalCount); - result.put("next", currPage == totalPage ? currPage : currPage + 1); - result.put("prev", currPage == 1 ? 1 : currPage - 1); + result.put("next", currPage == totalPage? currPage : currPage + 1); + result.put("prev", currPage == 1? 1 : currPage - 1); result.put("first", 1); result.put("last", totalPage); result.put("pageSize", pageSize); @@ -79,30 +154,56 @@ public class Result implements Serializable { } /** - * 失败响应 - * - * @param errorMsg - * @return + * 创建表示失败的操作结果对象，返回包含指定失败消息的`Result`实例，状态码会被设置为失败状态码（`FAIL_CODE`），结果数据默认为空字符串。 + * 通常在业务操作出现错误、未达到预期结果时使用该方法来构造失败的响应对象，并传递具体的失败原因消息给调用者。 + * + * @param errorMsg 具体的失败原因消息字符串，例如 "数据库连接失败"、"参数校验不通过" 等，将被赋值到`Result`对象的`message`字段中，方便调用者了解操作失败的具体原因。 + * @return 表示失败的`Result`对象，其状态码为`FAIL_CODE`，包含空的结果数据以及传入的失败原因消息字符串。 */ public static Result failResult(String errorMsg) { return result(FAIL_CODE, "", errorMsg); } + /** + * 创建`Result`对象的通用方法，根据传入的状态码、结果数据以及消息构建并返回一个`Result`对象实例，用于在不同的具体场景下灵活创建具有不同状态、数据和消息的`Result`对象。 + * + * @param code 要设置的状态码，通常使用`SUCCESS_CODE`表示成功，`FAIL_CODE`表示失败，也可以根据业务需求自定义其他状态码。 + * @param result 具体的结果数据，可以是各种类型的对象，例如查询到的用户信息列表、单个用户对象等，将被赋值到`Result`对象的`result`字段中。 + * @param message 要设置的提示消息字符串，例如操作成功或失败的相关描述信息等，将被赋值到`Result`对象的`message`字段中。 + * @return 根据传入参数构建好的`Result`对象实例，包含指定的状态码、结果数据以及消息内容。 + */ public static Result result(int code, Object result, String message) { Result res = new Result(code, result, message); return res; } + // 以下是用于获取`Result`对象中各个属性的公共访问方法，方便外部调用者获取`Result`对象封装的状态码、结果数据以及消息信息。 + + /** + * 获取`Result`对象的状态码。 + * + * @return `Result`对象中存储的状态码，调用者可根据该状态码判断操作是否成功以及进行相应的后续处理。 + */ public int getCode() { return code; } + /** + * 获取`Result`对象的结果数据。 + * + * @return `Result`对象中存储的结果数据，可以是各种类型的对象，例如查询到的用户信息列表、单个用户对象等，调用者可根据业务需求进一步处理该结果数据。 + */ public Object getResult() { return result; } + /** + * 获取`Result`对象的提示消息。 + * + * @return `Result`对象中存储的提示消息字符串，例如操作成功或失败的相关描述信息等，方便调用者了解操作的详细情况。 + */ public String getMessage() { return message; } -} +} \ No newline at end of file diff --git a/tamguo-common/src/main/java/com/tamguo/common/utils/Status.java b/tamguo-common/src/main/java/com/tamguo/common/utils/Status.java index 1bd741d..8e5a7d7 100644 --- a/tamguo-common/src/main/java/com/tamguo/common/utils/Status.java +++ b/tamguo-common/src/main/java/com/tamguo/common/utils/Status.java @@ -1,5 +1,12 @@ package com.tamguo.common.utils; +// Status枚举用于定义一组表示某种状态的常量值，在当前代码情境下，大概率是用于表示某个操作（比如文件上传、业务流程执行等相关操作）的不同结果状态， +// 通过使用枚举可以使代码更加清晰、易读，并且限定了合法的状态取值范围，避免使用随意的字符串或整数来表示状态而可能导致的混淆和错误。 public enum Status { - SUCCESS , ERROR -} + + // 表示操作成功的状态值，通常在相关操作顺利完成、达到预期结果时使用该枚举常量来标记成功状态，方便在代码中统一判断和处理操作成功的情况。 + SUCCESS, + + // 表示操作出现错误的状态值，用于在操作执行过程中发生异常、未达到预期等失败情况时进行标识，便于后续根据该状态执行相应的错误处理逻辑、返回错误提示信息等操作。 + ERROR +} \ No newline at end of file diff --git a/tamguo-common/src/main/java/com/tamguo/common/utils/UploaderMessage.java b/tamguo-common/src/main/java/com/tamguo/common/utils/UploaderMessage.java index 84fa24a..13ba625 100644 --- a/tamguo-common/src/main/java/com/tamguo/common/utils/UploaderMessage.java +++ b/tamguo-common/src/main/java/com/tamguo/common/utils/UploaderMessage.java @@ -2,66 +2,84 @@ package com.tamguo.common.utils; import java.util.ArrayList; - +// UploaderMessage类主要用于封装文件上传相关操作的结果信息，包含了文件上传的状态、状态消息、错误相关信息、文件路径以及文件所在的域名等内容，方便在文件上传操作完成后，统一向调用者反馈详细的情况。 public class UploaderMessage { + + // 用于表示文件上传操作的整体状态，通常会是一些预定义的枚举值（此处虽然未展示枚举定义，但推测`Status`是一个枚举类型），比如成功、失败、正在处理等不同的状态情况，方便外部调用者快速知晓文件上传的大致结果。 private Status status; + + // 用于存放关于文件上传状态的详细描述消息，例如在上传成功时可以是"文件上传成功"，出现部分问题时可以是具体的错误提示等，初始值为空字符串，后续可根据实际情况进行设置。 private String statusMsg = ""; + + // 用于存储文件上传过程中出现错误的相关键值（推测可能是与错误对应的一些标识编号等，具体含义取决于业务逻辑中对错误的定义和编码方式），使用ArrayList来存储多个整数值，方便记录多个可能出现的错误相关标识，初始值为null（在未添加元素时的默认情况）。 private ArrayList errorKys; + + // 用于存放文件上传操作出现错误时的具体错误信息，例如"文件大小超出限制"、"网络连接失败导致上传中断"等详细的错误描述内容，初始值为空字符串，当有错误发生时可设置相应的错误消息字符串。 private String error = ""; + + // 用于记录上传文件在服务器端存储的文件路径信息，方便后续需要访问该文件时能准确找到其位置，初始值为空字符串，在文件上传成功并确定存储路径后可进行设置。 private String filePath = ""; + + // 用于表示上传文件所在的域名信息，例如在有多个不同域名的服务器用于存储文件的场景下，指明该文件所属的具体域名，初始值为空字符串，可根据实际的文件存储配置进行设置。 private String fileDomain = ""; + // 获取文件上传操作的状态，外部调用者通过此方法可以获取到表示当前文件上传状态的枚举值（由`Status`类型表示），进而根据该状态进行相应的后续处理，比如展示不同的提示信息给用户等。 public Status getStatus() { return status; } + // 设置文件上传操作的状态，在文件上传过程中或者完成后，由相关的业务逻辑代码调用此方法，传入合适的`Status`枚举值来更新文件上传的状态信息，以便后续外部能获取到准确的状态情况。 public void setStatus(Status status) { this.status = status; } - public String getStatusMsg() { + // 获取文件上传状态的详细描述消息，外部调用者通过调用此方法能得到关于文件上传结果的详细文本描述信息，用于向用户展示或者记录日志等操作，展示更具体的文件上传情况反馈。 + public Status getStatusMsg() { return statusMsg; } + // 设置文件上传状态的详细描述消息，在文件上传的不同阶段，根据实际情况调用此方法来更新状态消息内容，比如在上传成功时设置为"文件已成功上传至服务器"，出现错误时设置相应的错误提示消息等。 public void setStatusMsg(String statusMsg) { this.statusMsg = statusMsg; } + // 获取文件上传过程中出现错误的相关键值列表，外部调用者可以通过此方法获取到记录错误相关标识编号的ArrayList，进而分析具体出现了哪些预定义的错误情况，方便进行针对性的错误处理或者统计等操作。 public ArrayList getErrorKys() { return errorKys; } + // 设置文件上传过程中出现错误的相关键值列表，当检测到文件上传出现错误并确定对应的错误标识编号后，通过此方法将包含这些编号的ArrayList传入，更新错误相关键值信息，以便后续获取和分析。 public void setErrorKys(ArrayList errorKys) { this.errorKys = errorKys; } + // 获取文件上传操作出现错误时的具体错误信息，外部调用者调用此方法能得到详细的错误描述字符串，用于向用户展示具体的错误原因或者记录到日志中进行错误排查等操作。 public String getError() { return error; } + // 设置文件上传操作出现错误时的具体错误信息，在文件上传出现错误并确定具体的错误原因后，通过此方法将错误消息字符串传入，更新错误信息内容，方便后续获取和展示给相关人员。 public void setError(String error) { this.error = error; } - public String getFilePath() { - return filePath; - } - - public void setFilePath(String filePath) { - this.filePath = filePath; - } - - public String getFileDomain() { - return fileDomain; - } - - public void setFileDomain(String fileDomain) { - this.fileDomain = fileDomain; - } - - -} - + // 获取上传文件在服务器端存储的文件路径信息，外部调用者可以通过此方法获取到文件的存储路径字符串，用于后续可能的文件访问、下载等操作，比如在前端页面展示文件链接供用户下载等场景。 + public String getFilePath() { + return filePath; + } + // 设置上传文件在服务器端存储的文件路径信息，在文件上传成功并确定其在服务器上的存储位置后，通过此方法将文件路径字符串传入，更新文件路径属性，以便后续能准确获取到该文件的存储位置信息。 + public void setFilePath(String filePath) { + this.filePath = filePath; + } + // 获取上传文件所在的域名信息，外部调用者调用此方法能得到文件所属的域名字符串，在涉及多域名文件存储或者需要明确文件来源域名等场景下有重要作用，例如根据域名进行不同的资源访问配置等操作。 + public String getFileDomain() { + return fileDomain; + } + // 设置上传文件所在的域名信息，当确定文件存储的具体域名后，通过此方法将域名字符串传入，更新文件域名属性，方便后续获取和使用该域名相关信息。 + public void setFileDomain(String fileDomain) { + this.fileDomain = fileDomain; + } +} \ No newline at end of file diff --git a/tamguo-common/src/main/java/com/tamguo/common/utils/XMLConfiguration.java b/tamguo-common/src/main/java/com/tamguo/common/utils/XMLConfiguration.java index 6737c2d..a804cdc 100644 --- a/tamguo-common/src/main/java/com/tamguo/common/utils/XMLConfiguration.java +++ b/tamguo-common/src/main/java/com/tamguo/common/utils/XMLConfiguration.java @@ -8,9 +8,23 @@ import javax.xml.parsers.DocumentBuilderFactory; import org.w3c.dom.Document; +// XMLConfiguration类主要用于读取XML配置文件，并将其解析为可操作的Document对象，方便后续对XML配置内容进行访问和处理，提供了从文件路径以及输入流两种方式读取XML配置文件的功能。 public class XMLConfiguration { + + // 用于存储解析后的XML文档对象，初始值为null，在成功调用读取配置文件的方法并解析成功后，会存放对应的Document对象，代表整个XML文档的树形结构，可用于后续的节点查询、数据提取等操作。 private Document document = null; + /** + * 从指定的文件路径读取XML配置文件，并尝试将其解析为Document对象。 + * 首先通过`DocumentBuilderFactory.newInstance()`方法获取一个`DocumentBuilderFactory`实例，它是创建`DocumentBuilder`对象的工厂类，用于配置和创建用于解析XML文档的构建器。 + * 接着在`try`块中，使用`dbf.newDocumentBuilder()`方法基于上述工厂类创建一个`DocumentBuilder`对象，该对象具备解析XML文档的能力。 + * 然后调用`db.parse(configFilename)`方法，将指定的文件路径（`configFilename`参数）对应的XML文件解析为`Document`对象，并赋值给`document`属性。 + * 如果在读取文件或者解析过程中出现`IOException`（例如文件不存在、无法读取文件等输入输出相关的异常情况）或者其他异常（例如XML格式不符合规范等导致解析失败的情况），会打印异常堆栈信息。 + * 最后判断`document`是否仍为`null`，如果是，则表示解析失败，返回`false`；若解析成功，`document`不为`null`，则返回`true`，告知调用者文件读取和解析操作是否成功。 + * + * @param configFilename 要读取的XML配置文件的完整文件路径字符串，例如 "/path/to/config.xml"，调用者需要确保路径指向的文件存在且具有可读权限。 + * @return 如果成功将指定的XML配置文件解析为`Document`对象，则返回`true`；若出现异常导致解析失败，`document`仍为`null`，则返回`false`。 + */ public boolean readConfigFile(String configFilename) { DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); try { @@ -27,6 +41,17 @@ public class XMLConfiguration { return true; } + /** + * 从给定的输入流（`InputStream`）中读取XML配置文件内容，并尝试将其解析为Document对象。 + * 同样先通过`DocumentBuilderFactory.newInstance()`获取`DocumentBuilderFactory`实例来配置创建解析器相关的工厂环境。 + * 在`try`块内，利用`dbf.newDocumentBuilder()`创建`DocumentBuilder`对象，然后调用`db.parse(stream)`方法，将传入的输入流（`stream`参数）中的XML数据解析为`Document`对象，并赋值给`document`属性。 + * 若在读取输入流或者解析过程中出现`IOException`（例如输入流读取错误、意外中断等情况）或者其他异常（例如XML格式问题导致解析失败等），会打印异常堆栈信息。 + * 最后通过判断`document`是否为`null`来确定解析是否成功，若为`null`则返回`false`，表示解析失败；不为`null`则返回`true`，说明成功将输入流中的XML数据解析为了`Document`对象。 + * 此方法常用于从网络流、内存中的字节流等非文件形式的数据源读取XML配置信息并进行解析的场景，提供了更灵活的读取方式。 + * + * @param stream 包含XML配置文件内容的输入流对象，例如可以是从网络请求获取的XML数据输入流、从内存字节数组转换而来的输入流等，调用者需要确保输入流中的数据是合法的XML格式内容。 + * @return 如果成功将输入流中的XML配置文件解析为`Document`对象，则返回`true`；若出现异常导致解析失败，`document`仍为`null`，则返回`false`。 + */ public boolean readConfigFile(InputStream stream) { DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); try { @@ -43,11 +68,21 @@ public class XMLConfiguration { return true; } + /** + * 获取解析后的XML文档对象，外部调用者可以通过此方法获取到之前成功读取和解析XML配置文件后得到的`Document`对象，进而利用相关的DOM API对XML文档中的节点、元素、属性等进行查询、修改等操作。 + * + * @return 解析后的XML文档对象，如果尚未成功读取和解析XML配置文件，可能返回`null`，调用者需要进行相应的判断处理。 + */ public Document getDocument() { return document; } + /** + * 受保护的方法，用于在类内部或者子类中设置解析后的XML文档对象，一般情况下外部调用者不应直接调用此方法，主要用于在特定的继承场景或者内部逻辑需要重新设置`document`对象时使用，以更新当前存储的XML文档内容。 + * + * @param document 要设置的新的XML文档对象，通常是经过重新解析或者从其他途径获取的合法的`Document`对象，会替换掉当前存储的`document`对象。 + */ protected void setDocument(Document document) { this.document = document; } -} +} \ No newline at end of file