diff --git a/src/documentation/xdocs/poifs/book.xml b/src/documentation/xdocs/poifs/book.xml index 652d55dd2c..7a7262409b 100644 --- a/src/documentation/xdocs/poifs/book.xml +++ b/src/documentation/xdocs/poifs/book.xml @@ -8,6 +8,7 @@ + diff --git a/src/documentation/xdocs/poifs/html/POIFSUseCases.html b/src/documentation/xdocs/poifs/html/POIFSUseCases.html deleted file mode 100755 index 7eddf0c35e..0000000000 --- a/src/documentation/xdocs/poifs/html/POIFSUseCases.html +++ /dev/null @@ -1,449 +0,0 @@ - - - - - - - - - - - - - -

POI Use Cases

-


-

-

Use Case 1: Read existing file -system

-

Primary Actor: POI client

-

Scope: POI

-

Level: Summary

-

Stakeholders and Interests:

- -

Precondition: None

-

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. POI client requests POI to read a - POI file system, providing an InputStream - containing POI file system in question.

    -

  2. POI reads from the InputStream - in 512 byte blocks

    -

  3. POI verifies that the first block - begins with the well known signature (0xE11AB1A1E011CFD0)

    -

  4. POI reads the Block Allocation - Table from the first block and, if necessary, from the XBAT blocks.

    -

  5. POI obtains the start block of the - Property Table and reads the Property Table (use case 9, read file)

    -

  6. POI reads the individual entries - in the Property Table

    -

  7. POI obtains the start block of the - Small Block Allocation Table and reads the Small Block Allocation - Table (use case 9, read file)

    -

  8. POI obtains the start block of the - Small Block store from the first entry in the Property Table and - reads the Small Block Array (use case 9, read file)

    -
-

Extensions:

-

2a. If the last -block read is not a 512 byte block, the InputStream -is not that of a POI file system, and POI throws an appropriate -exception.

-

3a. If the -signature is incorrect, the InputStream -is not that of a POI file system, and POI throws an appropriate -exception.

-

-
-

-

Use Case 2: Write file system

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition:

- -

or

- -

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. POI client - provides an OutputStream to - write the file system to.

    -

  2. POI gets the - sizes of the Property Table and each file in the file system.

    -

  3. If any files - in the file system requires storage in a Small Block Array, POI - creates a Small Block Array of sufficient size to hold all of the - small files.

    -

  4. POI - calculates the number of big blocks needed to hold all of the large - files, the Property Table, and, if necessary, the Small Block Array - and the Small Block Allocation Table.

    -

  5. POI creates a - set of big blocks sufficient to store the Block Allocation Table

    -

  6. POI creates - and writes the header block

    -

  7. POI writes - out the XBAT blocks, if needed.

    -

  8. POI writes - out the Small Block Array, if needed

    -

  9. POI writes - out the Small Block Allocation Table, if needed

    -

  10. POI writes - out the Property Table

    -

  11. POI writes - out the large files, if needed

    -

  12. POI closes - the OutputStream.

    -
-

Extensions:

-

6a. Exceptions -writing to the OutputStream -will be propagared back to the POI client.

-

7a. Exceptions -writing to the OutputStream -will be propagared back to the POI client.

-

8a. Exceptions -writing to the OutputStream -will be propagared back to the POI client.

-

9a. Exceptions -writing to the OutputStream -will be propagared back to the POI client.

-

10a. Exceptions -writing to the OutputStream -will be propagared back to the POI client.

-

11a. Exceptions -writing to the OutputStream -will be propagared back to the POI client.

-

12a. Exceptions -closing the OutputStream will -be propagared back to the POI client.

-


-

-

Use Case 3: Create new file -system

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition:

-

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. POI creates - an empty Property Table.

    -
-

Extensions: -None

-


-

-

Use Case 4: Replace file in file -system

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition:

-

Either

- -

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. POI discards - storage of the existing file.

    -

  2. POI updates - the existing file's entry in the Property Table

    -

  3. POI stores - the new file's data

    -
-

Extensions:

-

1a. POI throws an -exception if the file does not exist.

-


-

-

Use Case 5: Delete file from -file system

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition:

- -

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. POI discards - the specified file's storage

    -

  2. POI discards - the file's Property Table entry

    -
-

Extensions:

-

1a. POI throws an -exception if the file does not exist.

-


-

-

Use Case 6: Write new file to -file system

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition: -

- -

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. The POI - client provides a file name

    -

  2. POI creates a - new Property Table entry for the new file

    -

  3. POI - provides the POI client with an OutputStream - to write to.

    -

  4. The POI client writes data to the - provided OutputStream.

    -

  5. The POI client closes the provided - OutputStream

    -

  6. POI updates the Property Table - entry with the new file's size

    -
-

Extensions:

-

1a. POI throws an -exception if a file with the specified name already exists in the -file system.

-

1b. POI throws an -exception if the file name is too long. The limit on file name length -is 32 characters.

-


-

-

Use Case 7: Read existing file -from file system

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition:

- -

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. The POI - client provides the name of a file to be read

    -

  2. POI provides - an InputStream to read from.

    -

  3. The POI - client reads from the InputStream.

    -

  4. The POI - client closes the InputStream.

    -
-

Extensions:

-

1a. POI throws an -exception if no file with the specified name exists.

-


-

-

Use Case 8: Read file system -directory

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition:

- -

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. The POI - client requests the file system directory.

    -

  2. POI returns - an Iterator. The Iterator - will not include the root entry in the Property Table, and may be an - Iterator over an empty - Collection.

    -
-

Extensions: -None

-


-

-

Use Case 9: Read file

-

Primary Actor: POI

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition: None

-

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. POI begins - with a start block, a file size, and a flag indicating whether to - use the Big Block Allocation Table or the Small Block Allocation - Table

    -

  2. POI returns - an InputStream.

    -

  3. Reads from - the InputStream are performed by walking the specified Block - Allocation Table and reading the blocks indicated.

    -

  4. POI closes - the InputStream when finished reading the file, or its client wants - to close the InputStream.

    -
-

Extensions:

-

3a. An exception -will be thrown if the specified Block Allocation Table is corrupt, as -evidenced by an index pointing to a non-existent block, or by a chain -extending past the known size of the file.

-


-

-

Use Case 10: Rename existing -file in file system

-

Primary Actor: POI client

-

Scope: POI

-

-Level: Summary

-

Stakeholders and Interests:

- -

Precondition: -

- -

Minimal Guarantee: None

-

Main Success Guarantee:

-
    -

  1. POI updates - the Property Table entry for the specified file with its new name.

    -
-

Extensions:

-

1a. If the old -file name is not in the file system, POI throws an exception.

-

1b. If the new -file name already exists in the file system, POI throws an exception.

-

1c. If the new -file name is too long (the limit is 32 characters), POI throws an -exception.

-


-

- - \ No newline at end of file diff --git a/src/documentation/xdocs/poifs/usecases.xml b/src/documentation/xdocs/poifs/usecases.xml new file mode 100644 index 0000000000..5880abe3e8 --- /dev/null +++ b/src/documentation/xdocs/poifs/usecases.xml @@ -0,0 +1,689 @@ + + + +
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to read content of file + system
    • +
  • POIFS - understands POIFS file system
    • +
+
Precondition:None
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. POIFS client requests POIFS to read a POIFS file + system, providing an InputStream + containing POIFS file system in question.
    2. +
  2. POIFS reads from the InputStream in + 512 byte blocks
    3. +
  3. POIFS verifies that the first block begins with + the well known signature + (0xE11AB1A1E011CFD0)
    4. +
  4. POIFS reads the Block Allocation Table from the + first block and, if necessary, from the XBAT + blocks.
    5. +
  5. POIFS obtains the start block of the Property + Table and reads the Property Table (use case 9, + read file)
    6. +
  6. POIFS reads the individual entries in the Property + Table
    7. +
  7. POIFS obtains the start block of the Small Block + Allocation Table and reads the Small Block + Allocation Table (use case 9, read file)
    8. +
  8. POIFS obtains the start block of the Small Block + store from the first entry in the Property Table + and reads the Small Block Array (use case 9, read + file)
    9. +
+
Extensions: +
    +
  • 2a. If the last block read is not a 512 byte + block, the InputStream is not that of + a POIFS file system, and POIFS throws an + appropriate exception.
    • +
  • 3a. If the signature is incorrect, the + InputStream is not that of a POIFS + file system, and POIFS throws an appropriate + exception.
    • +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to write file system out.
    • +
  • POIFS - knows how to write file system out.
    • +
+
Precondition: +
    +
  • File system has been read (use case 1, read + existing file system) and subsequently modified + (use case 4, replace file in file system; use case + 5, delete file from file system; or use case 6, + write new file to file system; in any + combination)
    • +
+

or

+
    +
  • File system has been created (use case 3, create + new file system)
    • +
+
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. POIFS client provides an OutputStream + to write the file system to.
    2. +
  2. POIFS gets the sizes of the Property Table and + each file in the file system.
    3. +
  3. If any files in the file system requires storage + in a Small Block Array, POIFS creates a Small + Block Array of sufficient size to hold all of the + small files.
    4. +
  4. POIFS calculates the number of big blocks needed + to hold all of the large files, the Property + Table, and, if necessary, the Small Block Array + and the Small Block Allocation Table.
    5. +
  5. POIFS creates a set of big blocks sufficient to + store the Block Allocation Table
    6. +
  6. POIFS creates and writes the header block
    7. +
  7. POIFS writes out the XBAT blocks, if needed.
    8. +
  8. POIFS writes out the Small Block Array, if + needed
    9. +
  9. POIFS writes out the Small Block Allocation Table, + if needed
    10. +
  10. POIFS writes out the Property Table
    11. +
  11. POIFS writes out the large files, if needed
    12. +
  12. POIFS closes the OutputStream.
    13. +
+
Extensions: +
    +
  • 6a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client.
    • +
  • 7a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client.
    • +
  • 8a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client.
    • +
  • 9a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client.
    • +
  • 10a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client.
    • +
  • 11a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client.
    • +
  • 12a. Exceptions closing the + OutputStream will be propagated back + to the POIFS client.
    • +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to create a new file + system
    • +
  • POIFS - knows how to create a new file system
    • +
+
Precondition:None
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. POIFS creates an empty Property Table.
    2. +
+
Extensions:None
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to replace an existing file in + the file system
    • +
  • POIFS - knows how to manage the file system
    • +
+
Precondition: +

Either

+
    +
  • The file system has been read (use case 1, read + existing file system) and a file has been + extracted from the file system (use case 7, read + existing file from file system)
    • +
+

or

+
    +
  • The file system has been created (use case 3, + create new file system) and a file has been + written to the file system (use case 6, write new + file to file system)
    • +
+
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. POIFS discards storage of the existing file.
    2. +
  2. POIFS updates the existing file's entry in the + Property Table
    3. +
  3. POIFS stores the new file's data
    4. +
+
Extensions: +
    +
  • 1a. POIFS throws an exception if the file does not + exist.
    • +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to remove a file from a file + system
    • +
  • POIFS - knows how to manage the file system
    • +
+
Precondition: +

Either

+
    +
  • The file system has been read (use case 1, read + existing file system) and a file has been + extracted from the file system (use case 7, read + existing file from file system)
    • +
+

or

+
    +
  • The file system has been created (use case 3, + create new file system) and a file has been + written to the file system (use case 6, write new + file to file system)
    • +
+
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. POIFS discards the specified file's storage.
    2. +
  2. POIFS discards the file's Property Table + entry.
    3. +
+
Extensions: +
    +
  • 1a. POIFS throws an exception if the file does not + exist.
    • +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to add a new file to the file + system
    • +
  • POIFS - knows how to manage the file system
    • +
+
Precondition:The specified file does not yet exist in the file + system
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. The POIFS client provides a file name
    2. +
  2. POIFS creates a new Property Table entry for the + new file
    3. +
  3. POIFS provides the POIFS client with an + OutputStream to write to.
    4. +
  4. The POIFS client writes data to the provided + OutputStream.
    5. +
  5. The POIFS client closes the provided + OutputStream
    6. +
  6. POIFS updates the Property Table entry with the + new file's size
    7. +
+
Extensions: +
    +
  • 1a. POIFS throws an exception if a file with the + specified name already exists in the file + system.
    • +
  • 1b. POIFS throws an exception if the file name is + too long. The limit on file name length is 31 + characters.
    • +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to read a file from the file + system
    • +
  • POIFS - knows how to manage the file system
    • +
+
Precondition: +
    +
  • The file system has been read (use case 1, read + existing file system) or has been created and + written to (use case 3, create new file system; + use case 6, write new file to file system).
    • +
  • The specified file exists in the file system.
    • +
+
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. The POIFS client provides the name of a file to be + read
    2. +
  2. POIFS provides an InputStream to read + from.
    3. +
  3. The POIFS client reads from the + InputStream.
    4. +
  4. The POIFS client closes the + InputStream.
    5. +
+
Extensions:1a. POIFS throws an exception if no file with the + specified name exists.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to know what files exist in + the file system
    • +
  • POIFS - knows how to manage the file system
    • +
+
Precondition:The file system has been read (use case 1, read + existing file system) or created (use case 3, create + new file system)
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. The POIFS client requests the file system + directory.
    2. +
  2. POIFS returns an Iterator. The + Iterator will not include the root + entry in the Property Table, and may be an + Iterator over an empty + Collection.
    3. +
+
Extensions:None
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS - POIFS needs to read a file, or something + resembling a file (i.e., the Property Table, the + Small Block Array, or the Small Block Allocation + Table)
    • +
+
Precondition:None
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. POIFS begins with a start block, a file size, and + a flag indicating whether to use the Big Block + Allocation Table or the Small Block Allocation + Table
    2. +
  2. POIFS returns an InputStream.
    3. +
  3. Reads from the InputStream are + performed by walking the specified Block + Allocation Table and reading the blocks + indicated.
    4. +
  4. POIFS closes the InputStream when + finished reading the file, or its client wants to + close the InputStream.
    5. +
+
Extensions:3a. An exception will be thrown if the specified Block + Allocation Table is corrupt, as evidenced by an index + pointing to a non-existent block, or by a chain + extending past the known size of the file.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: +
    +
  • POIFS client- wants to rename an existing file in + the file system.
    • +
  • POIFS - knows how to manage the file system.
    • +
+
Precondition: +
    +
  • The file system is has been read (use case 1, read + existing file system) or has been created and + written to (use case 3, create new file system; + use case 6, write new file to file system.
    • +
  • The specified file exists in the file system.
    • +
  • The new name for the file does not duplicate + another file in the file system.
    • +
+
Minimal Guarantee:None
Main Success Guarantee: +
    +
  1. POIFS updates the Property Table entry for the + specified file with its new name.
    2. +
+
Extensions: +
    +
  • 1a. If the old file name is not in the file + system, POIFS throws an exception.
    • +
  • 1b. If the new file name already exists in the + file system, POIFS throws an exception.
    • +
  • 1c. If the new file name is too long (the limit is + 31 characters), POIFS throws an exception.
    • +
+
+ + + +