1 /*
2 * Copyright 2016-2022 The OSHI Project Contributors
3 * SPDX-License-Identifier: MIT
4 */
5 package oshi.hardware;
6
7 import java.util.List;
8
9 import oshi.annotation.concurrent.ThreadSafe;
10
11 /**
12 * A storage mechanism where data are recorded by various electronic, magnetic, optical, or mechanical changes to a
13 * surface layer of one or more rotating disks or or flash storage such as a removable or solid state drive. In
14 * constrast to a File System, defining the way an Operating system uses the storage, the Disk Store represents the
15 * hardware which a FileSystem uses for its File Stores.
16 * <p>
17 * Thread safe for the designed use of retrieving the most recent data. Users should be aware that the
18 * {@link #updateAttributes()} method may update attributes, including the time stamp, and should externally synchronize
19 * such usage to ensure consistent calculations.
20 */
21 @ThreadSafe
22 public interface HWDiskStore {
23
24 /**
25 * The disk name
26 *
27 * @return the name
28 */
29 String getName();
30
31 /**
32 * The disk model
33 *
34 * @return the model
35 */
36 String getModel();
37
38 /**
39 * The disk serial number, if available.
40 *
41 * @return the serial number
42 */
43 String getSerial();
44
45 /**
46 * The size of the disk
47 *
48 * @return the disk size, in bytes
49 */
50 long getSize();
51
52 /**
53 * The number of reads from the disk
54 *
55 * @return the reads
56 */
57 long getReads();
58
59 /**
60 * The number of bytes read from the disk
61 *
62 * @return the bytes read
63 */
64 long getReadBytes();
65
66 /**
67 * The number of writes to the disk
68 *
69 * @return the writes
70 */
71 long getWrites();
72
73 /**
74 * The number of bytes written to the disk
75 *
76 * @return the bytes written
77 */
78 long getWriteBytes();
79
80 /**
81 * The length of the disk queue (#I/O's in progress). Includes I/O requests that have been issued to the device
82 * driver but have not yet completed. Not supported on macOS.
83 *
84 * @return the current disk queue length
85 */
86 long getCurrentQueueLength();
87
88 /**
89 * The time spent reading or writing, in milliseconds.
90 *
91 * @return the transfer time
92 */
93 long getTransferTime();
94
95 /**
96 * The partitions on this disk.
97 *
98 * @return an {@code UnmodifiableList} of the partitions on this drive.
99 */
100 List<HWPartition> getPartitions();
101
102 /**
103 * The time this disk's statistics were updated.
104 *
105 * @return the timeStamp, in milliseconds since the epoch.
106 */
107 long getTimeStamp();
108
109 /**
110 * Make a best effort to update all the statistics about the drive without needing to recreate the drive list. This
111 * method provides for more frequent periodic updates of individual drive statistics but may be less efficient to
112 * use if updating all drives. It will not detect if a removable drive has been removed and replaced by a different
113 * drive in between method calls.
114 *
115 * @return True if the update was (probably) successful, false if the disk was not found
116 */
117 boolean updateAttributes();
118 }