|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.EncryptionHandler
An EncryptionHandler is the abstract superclass of all algorithms that are used to encrypt a PDF document before saving. Encryption is required to enforce any sorts of restriction on a PDF, whether it be that it requires a password to open, it can only be opened by a user posessing a certain private key, or just that it can't be printed or altered.
Although currently the PDF library is only supplied with a single
implementation of this class (the StandardEncryptionHandler
),
it is possible for end-users to implement their own versions of
this class to allow PDF's to be created for custom encryption handlers,
such as might be required for e-Books (for example).
The following information is for those who will be creating a concrete implementation of this class.
When encrypting, the PDF.render(java.io.OutputStream)
method will call the prepareToEncrypt()
method,
followed by n number of calls to (setObject(int, int)
, getEncryptionStream(java.io.OutputStream)
), then
finally followed by a call to finishedEncrypt()
(the decryption process is the same,
except substitute the word "Decrypt" for Encrypt
in the method names above).
The two prepare...
methods can store and retrieve values out
of the Encrypt
dictionary by calling the various get...
and put...
methods. These methods expect the key to be specified as a String. At it's simplest, a
method call like putNameValue("Filter", "Standard")
would create a PDF Name object
called "Filter" in the Encrypt
dictionary. For nested objects, Arrays and Dictionary objects
can be referenced by placing a "." between field names. For example, "MyArray.2.Name" references
the object called "Name" in the Dictionary which is the second entry in the "MyArray" array of
the Encrypt
dictionary. All objects added this way are "direct" - it is not
possible to add indirect objects to the encryption dictionary or it's children.
An EncryptionHandler may be used for both decryption and encryption if the document is read and
then written again, so it's important that any values read from the Encrypt
dictionary during
the prepareToDecrypt()
method are available to be reused in the prepareToEncrypt()
method.
Finally, care needs to be taken about any references to Object
instances when an instance
is cloned - which it will be when a PDF containing an EncryptionHandler is cloned.
PDF.setEncryptionHandler(org.faceless.pdf2.EncryptionHandler)
,
PDFReader.PDFReader(InputStream, EncryptionHandler)
Constructor Summary | |
protected |
EncryptionHandler()
|
Method Summary | |
Object |
clone()
|
protected boolean |
containsKey(String key)
Return true if the Encrypt dictionary contains the specified key |
abstract void |
finishedDecrypt()
This method is called after the PDF has been read. |
abstract void |
finishedEncrypt()
This method is called after the PDF has been written. |
protected int |
getArrayValueSize(String key)
Return the size of the specified Array from the Encrypt dictionary,
or -1 if no such field exists |
protected boolean |
getBooleanValue(String key)
Return a Boolean from the Encrypt dictionary as a boolean
or false if no such field exists |
abstract OutputStream |
getDecryptionStream(OutputStream out)
Return a FilterOutputStream that will decrypt anything written to it. |
protected Set |
getDictionaryValueKeys(String key)
Return the Set of keys of the specified Dictionary from the Encrypt dictionary,
or null if no such field exists. |
abstract OutputStream |
getEncryptionStream(OutputStream out)
Return a FilterOutputStream that will encrypt anything written to it. |
protected byte[] |
getFileId()
This method returns the the file ID of the document, as set by setFileId(byte[]) . |
abstract String |
getFilterName()
Return the name of the "Filter" field in the Encryption dictionary. |
protected String |
getNameValue(String key)
Return a Name from the Encrypt dictionary as a String
or null if no such field exists |
protected float |
getNumericValue(String key)
Return a Number from the Encrypt dictionary as a float
or Float.NaN if no such field exists |
protected byte[] |
getStringValue(String key)
Return a String from the Encrypt dictionary as a byte array
or null if no such field exists |
abstract String |
getSubFilterName()
Return the name of the "Subfilter" field in the Encryption dictionary. |
protected String |
getTextStringValue(String key)
Return a Text String from the Encrypt dictionary as a String
or null if no such field exists |
abstract boolean |
isRequired()
This method should return true if the document needs to be encrypted. |
abstract void |
prepareToDecrypt()
This method is called just before the PDF is read in. |
abstract void |
prepareToEncrypt()
This method is called when the PDF is about to be written out. |
protected void |
putArrayValue(String key)
Add (or replace) an Array to the Encrypt dictionary. |
protected void |
putBooleanValue(String key,
boolean val)
Add (or replace) a Boolean to the Encrypt dictionary.
|
protected void |
putDictionaryValue(String key)
Add (or replace) a Dictionary to the Encrypt dictionary. |
protected void |
putNameValue(String key,
String val)
Add (or replace) a Name to the Encrypt dictionary.
|
protected void |
putNumericValue(String key,
float val)
Add (or replace) a Number to the Encrypt dictionary.
|
protected void |
putStringValue(String key,
byte[] val)
Add (or replace) a String to the Encrypt dictionary.
|
protected void |
putTextStringValue(String key,
String val)
Add (or replace) a Text String to the Encrypt dictionary.
|
void |
setFileId(byte[] in)
This method is called to set the file ID of the document. |
abstract void |
setObject(int object,
int generation)
This method is called just before each object is encrypted. |
Methods inherited from class java.lang.Object |
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
protected EncryptionHandler()
Method Detail |
public abstract String getFilterName()
StandardEncryptionHandler
class returns "Standard" from this method.
public abstract String getSubFilterName()
null
.
public abstract OutputStream getEncryptionStream(OutputStream out)
FilterOutputStream
that will encrypt anything written to it. The encryption
parameters should have already been set by the call to prepareToEncrypt()
, which is
called once at the start of the render, and setObject(int, int)
, which is called just before
each object is rendered.
public abstract OutputStream getDecryptionStream(OutputStream out)
FilterOutputStream
that will decrypt anything written to it. The decryption
parameters should have already been set by the call to prepareToDecrypt()
, which is
called once at the start of the PDF read, and setObject(int, int)
, which is called just before
each object is read.
public abstract void prepareToDecrypt() throws IOException
Encrypt
dictionary by way of the various get...
methods, and use them and the value of getFileId()
to set its internal state so that
it's ready to start decryption. It may throw an IOException
if these parameters
are invalid, in which case the document cannot be read.
IOException
public abstract void prepareToEncrypt() throws IOException
Encrypt
dictionary
(including the "Filter" field) by way of the various put...
methods, and will use
these and the value of getFileId()
to set its internal state so that it's ready to
start encryption. It may throw an IOException
if these parameters are in any
way invalid, in which case the document cannot be written.
IOException
public abstract void finishedDecrypt()
public abstract void finishedEncrypt()
public abstract boolean isRequired()
true
if the document needs to be encrypted. For example,
the StandardEncryptionHandler
returns false
here if and only if no passwords
are set and the document is set to allow full access.
public abstract void setObject(int object, int generation)
getEncryptionStream(java.io.OutputStream)
and
getEncryptionStream(java.io.OutputStream)
methods
public final void setFileId(byte[] in)
protected final byte[] getFileId()
setFileId(byte[])
.
public Object clone()
protected boolean containsKey(String key)
Encrypt
dictionary contains the specified key
protected final byte[] getStringValue(String key)
Encrypt
dictionary as a byte array
or null
if no such field exists
protected final String getTextStringValue(String key)
Encrypt
dictionary as a String
or null
if no such field exists
protected final String getNameValue(String key)
Encrypt
dictionary as a String
or null
if no such field exists
protected final float getNumericValue(String key)
Encrypt
dictionary as a float
or Float.NaN
if no such field exists
protected final boolean getBooleanValue(String key)
Encrypt
dictionary as a boolean
or false
if no such field exists
protected final int getArrayValueSize(String key)
Encrypt
dictionary,
or -1
if no such field exists
protected final Set getDictionaryValueKeys(String key)
Encrypt
dictionary,
or null
if no such field exists.
protected final void putStringValue(String key, byte[] val)
Encrypt
dictionary.
A value of null
removes the entry.
protected final void putTextStringValue(String key, String val)
Encrypt
dictionary.
A value of null
removes the entry
protected final void putNumericValue(String key, float val)
Encrypt
dictionary.
A value of Float.NaN
removes the entry.
protected final void putNameValue(String key, String val)
Encrypt
dictionary.
A value of null
removes the entry.
protected final void putBooleanValue(String key, boolean val)
Encrypt
dictionary.
A value of null
removes the entry.
protected final void putArrayValue(String key)
Encrypt
dictionary.
protected final void putDictionaryValue(String key)
Encrypt
dictionary.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |