From cfc6d0a6032a7b0c518f6426bb6dd0130341eb17 Mon Sep 17 00:00:00 2001
From: Brian Carrier <carrier@sleuthkit.org>
Date: Tue, 8 Sep 2015 09:24:03 -0400
Subject: [PATCH] Make API docs sorted, added deprecated doxygen tags, added
TskData comments
---
bindings/java/doxygen/Doxyfile | 6 +-
.../sleuthkit/datamodel/SleuthkitCase.java | 28 ++---
.../src/org/sleuthkit/datamodel/TskData.java | 105 ++++++++++--------
3 files changed, 78 insertions(+), 61 deletions(-)
diff --git a/bindings/java/doxygen/Doxyfile b/bindings/java/doxygen/Doxyfile
index a868cea46..672c8a7e1 100644
--- a/bindings/java/doxygen/Doxyfile
+++ b/bindings/java/doxygen/Doxyfile
@@ -471,7 +471,7 @@ SORT_MEMBER_DOCS = YES
# by member name. If set to NO (the default) the members will appear in
# declaration order.
-SORT_BRIEF_DOCS = NO
+SORT_BRIEF_DOCS = YES
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen
# will sort the (brief and detailed) documentation of class members so that
@@ -481,7 +481,7 @@ SORT_BRIEF_DOCS = NO
# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO
# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO.
-SORT_MEMBERS_CTORS_1ST = NO
+SORT_MEMBERS_CTORS_1ST = YES
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the
# hierarchy of group names into alphabetical order. If set to NO (the default)
@@ -497,7 +497,7 @@ SORT_GROUP_NAMES = NO
# Note: This option applies only to the class list, not to the
# alphabetical list.
-SORT_BY_SCOPE_NAME = NO
+SORT_BY_SCOPE_NAME = YES
# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to
# do proper type resolution of all parameters of a function it will reject a
diff --git a/bindings/java/src/org/sleuthkit/datamodel/SleuthkitCase.java b/bindings/java/src/org/sleuthkit/datamodel/SleuthkitCase.java
index 17a438556..d8b16dea2 100644
--- a/bindings/java/src/org/sleuthkit/datamodel/SleuthkitCase.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/SleuthkitCase.java
@@ -3260,8 +3260,9 @@ public long countFilesWhere(String sqlWhereClause) throws TskCoreException {
/**
* Find and return list of all (abstract) files matching the specific Where
- * clause
- *
+ * clause.
+ * You need to know the database schema to use this, which is outlined on the
+ * <a href="http://wiki.sleuthkit.org/index.php?title=SQLite_Database_v3_Schema">wiki</a>. You should use enums from org.sleuthkit.datamodel.TskData to make the queries easier to maintain and understand.
* @param sqlWhereClause a SQL where clause appropriate for the desired
* files (do not begin the WHERE clause with the word WHERE!)
* @return a list of AbstractFile each of which satisfy the given WHERE
@@ -3325,8 +3326,9 @@ public List<Long> findAllFileIdsWhere(String sqlWhereClause) throws TskCoreExcep
* files (do not begin the WHERE clause with the word WHERE!)
* @return a list of FsContent each of which satisfy the given WHERE clause
* @throws TskCoreException
+ * @deprecated use SleuthkitCase.findAllFilesWhere() instead
*/
- @Deprecated // use findAllFilesWhere instead
+ @Deprecated
public List<FsContent> findFilesWhere(String sqlWhereClause) throws TskCoreException {
CaseDbConnection connection = connections.getConnection();
acquireSharedLock();
@@ -4095,7 +4097,7 @@ private List<FsContent> resultSetToFsContents(ResultSet rs) throws SQLException
* @throws SQLException if error occurred during the query
* @deprecated use specific datamodel methods that encapsulate SQL layer
*/
- @Deprecated
+ @Deprecated
public ResultSet runQuery(String query) throws SQLException {
CaseDbConnection connection;
try {
@@ -4120,7 +4122,7 @@ public ResultSet runQuery(String query) throws SQLException {
* @throws SQLException of closing the query results failed
* @deprecated use specific datamodel methods that encapsulate SQL layer
*/
- @Deprecated
+ @Deprecated
public void closeRunQuery(ResultSet resultSet) throws SQLException {
final Statement statement = resultSet.getStatement();
resultSet.close();
@@ -4399,7 +4401,7 @@ public int countFilesMd5Hashed() {
*
* @deprecated
*/
- @Deprecated
+ @Deprecated
public interface ErrorObserver {
void receiveError(String context, String errorMessage);
@@ -4408,10 +4410,10 @@ public interface ErrorObserver {
/**
* This is a temporary workaround to avoid an API change.
*
- * @deprecated
* @param observer The observer to add.
+ * @deprecated
*/
- @Deprecated
+ @Deprecated
public void addErrorObserver(ErrorObserver observer) {
errorObservers.add(observer);
}
@@ -4419,10 +4421,10 @@ public void addErrorObserver(ErrorObserver observer) {
/**
* This is a temporary workaround to avoid an API change.
*
- * @deprecated
* @param observer The observer to remove.
- */
- @Deprecated
+ * @deprecated
+ */
+ @Deprecated
public void removerErrorObserver(ErrorObserver observer) {
int i = errorObservers.indexOf(observer);
if (i >= 0) {
@@ -4433,11 +4435,11 @@ public void removerErrorObserver(ErrorObserver observer) {
/**
* This is a temporary workaround to avoid an API change.
*
- * @deprecated
* @param context The context in which the error occurred.
* @param errorMessage A description of the error that occurred.
+ * @deprecated
*/
- @Deprecated
+ @Deprecated
public void submitError(String context, String errorMessage) {
for (ErrorObserver observer : errorObservers) {
observer.receiveError(context, errorMessage);
diff --git a/bindings/java/src/org/sleuthkit/datamodel/TskData.java b/bindings/java/src/org/sleuthkit/datamodel/TskData.java
index 86698d659..7ad1901be 100644
--- a/bindings/java/src/org/sleuthkit/datamodel/TskData.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/TskData.java
@@ -24,14 +24,17 @@
import java.util.Set;
/**
- * Maps data integer and binary data stored into the database into string or
- * enum form.
+ * Contains enums for the integer values stored in the database and returned by the
+ * various data model objects.
*/
public class TskData {
private static ResourceBundle bundle = ResourceBundle.getBundle("org.sleuthkit.datamodel.Bundle");
- // Enum for Directory Type
+ /**
+ * The type of the file system file, as reported in the name structure of the file system.
+ * This is the dir_type column in the tsk_files table.
+ */
public enum TSK_FS_NAME_TYPE_ENUM {
UNDEF(0, "-"), ///< Unknown type
@@ -89,9 +92,10 @@ static public TSK_FS_NAME_TYPE_ENUM valueOf(short dir_type) {
}
}
- /**
- * Meta Type
- */
+ /**
+ * The type of the file system file, as reported in the metadata structure of the file system.
+ * This is the meta_type column in the tsk_files table.
+ */
public enum TSK_FS_META_TYPE_ENUM {
TSK_FS_META_TYPE_UNDEF(0, "-"),
@@ -139,9 +143,10 @@ public static TSK_FS_META_TYPE_ENUM valueOf(short metaType) {
}
}
- /**
- * FS Flags
- */
+ /**
+ * The allocated status of a file system file, as reported in the name structure of the file system.
+ * This is the dir_flags column in the tsk_files table.
+ */
public enum TSK_FS_NAME_FLAG_ENUM {
ALLOC(1, bundle.getString("TskData.tskFsNameFlagEnum.allocated")), ///< Name is in an allocated state
@@ -186,9 +191,10 @@ public static TSK_FS_NAME_FLAG_ENUM valueOf(int dirFlag) {
}
}
- /**
- * META flags
- */
+ /**
+ * The allocated status of the file system file, as reported in the metadata structure of the file system.
+ * This is the meta_flags column in the tsk_files table.
+ */
public enum TSK_FS_META_FLAG_ENUM {
ALLOC(1, bundle.getString("TskData.tskFsMetaFlagEnum.allocated")), ///< Metadata structure is currently in an allocated state
@@ -255,9 +261,10 @@ public static short toInt(Set<TSK_FS_META_FLAG_ENUM> metaFlags) {
}
- /**
- * These are based on the NTFS type values. Added types for HFS+.
- */
+ /**
+ * Type of data that is stored in the attribute for a file system file.
+ * This is the attr_type column in the tsk_files table.
+ */
public enum TSK_FS_ATTR_TYPE_ENUM {
TSK_FS_ATTR_TYPE_NOT_FOUND(0x00), // 0
@@ -311,7 +318,8 @@ public static TSK_FS_ATTR_TYPE_ENUM valueOf(int val) {
};
/**
- * Volume system flags
+ * Flags for a partition in the disk image.
+ * This is the flags column in the tsk_vs_parts table.
*/
public enum TSK_VS_PART_FLAG_ENUM {
@@ -337,9 +345,10 @@ public long getVsFlag() {
}
- /**
- * Meta mode
- */
+ /**
+ * The permissions of a file system file.
+ * This is the mode column in the tsk_files table.
+ */
public enum TSK_FS_META_MODE_ENUM {
/* The following describe the file permissions */
@@ -408,9 +417,11 @@ public static short toInt(Set<TSK_FS_META_MODE_ENUM> modes) {
}
};
- /**
- * File system type enum
- */
+
+ /**
+ * The type of the file system.
+ * This is the fs_type column in the tsk_fs_info table.
+ */
public enum TSK_FS_TYPE_ENUM {
TSK_FS_TYPE_DETECT(0x00000000), ///< Use autodetection methods
@@ -475,11 +486,11 @@ public static TSK_FS_TYPE_ENUM valueOf(int fsTypeValue) {
};
- /**
- * Image type
- */
- public enum TSK_IMG_TYPE_ENUM {
- /* The following describe the image type */
+ /**
+ * The type of the disk image.
+ * This is the types column in the tsk_images_info table.
+ */
+ public enum TSK_IMG_TYPE_ENUM {
TSK_IMG_TYPE_DETECT(0, bundle.getString("TskData.tskImgTypeEnum.autoDetect")), // Auto Detection
TSK_IMG_TYPE_RAW_SING(1, bundle.getString("TskData.tskImgTypeEnum.rawSingle")), // Single raw file (dd)
@@ -528,10 +539,11 @@ public String getName() {
}
};
- /**
- * Volume System type
- */
- public enum TSK_VS_TYPE_ENUM {
+ /**
+ * The type of the partition in the partition table.
+ * This is the flags column in the tsk_vs_parts table.
+ */
+ public enum TSK_VS_TYPE_ENUM {
TSK_VS_TYPE_DETECT(0x0000, bundle.getString("TskData.tskVSTypeEnum.autoDetect")), ///< Use autodetection methods
TSK_VS_TYPE_DOS(0x0001, "DOS"), ///< DOS Partition table NON-NLS
@@ -579,16 +591,18 @@ public String getName() {
}
};
- /**
- * Object type
- */
+
+ /**
+ * High-level type of an object from the database.
+ * This is the type column in the tsk_objects table.
+ */
public enum ObjectType {
- IMG(0),
- VS(1),
- VOL(2),
- FS(3),
- ABSTRACTFILE(4);
+ IMG(0), ///< Disk Image - see tsk_image_info for more details
+ VS(1), ///< Volume System - see tsk_vs_info for more details
+ VOL(2), ///< Volume - see tsk_vs_parts for more details
+ FS(3), ///< File System - see tsk_fs_info for more details
+ ABSTRACTFILE(4); ///< File - see tsk_files for more details
private short objectType;
@@ -622,9 +636,9 @@ public static ObjectType valueOf(short objectType) {
}
}
- /**
- * DB files type
- */
+ /**
+ * The type of file in a database, such as file system versus local file.
+ * This is the type field in the tsk_files table. */
public enum TSK_DB_FILES_TYPE_ENUM {
FS(0, "File System"), ///< File that can be found in file system tree.
@@ -674,9 +688,10 @@ public String getName() {
}
}
- /**
- * FileKnown status
- */
+ /**
+ * Identifies if a file was in a hash database or not.
+ * This is the known column in the tsk_files table.
+ */
public enum FileKnown {
UNKNOWN(0, bundle.getString("TskData.fileKnown.unknown")), ///< File marked as unknown by hash db
--
GitLab