## com.arsdigita.docmgr
Class File

    java.lang.Object
      com.arsdigita.domain.DomainObject
          com.arsdigita.domain.ObservableDomainObject
              com.arsdigita.kernel.ACSObject
                  com.arsdigita.versioning.VersionedACSObject
                      com.arsdigita.docmgr.ResourceImpl
                          com.arsdigita.docmgr.File

All Implemented Interfaces:
  com.arsdigita.auditing.Audited, Constants, Resource

public class File
extends ResourceImpl
implements Constants

Represents a File in the document manager application.

Version:
  $Id: //apps/docmgr/dev/src/com/arsdigita/docmgr/File.java#19 $
Author:
  Stefan Deusch (stefan@arsdigita.com), Ron Henderson (ron@arsdigita.com)

Field Summary
`static String` `BASE_DATA_OBJECT_TYPE`
`static String` `DEFAULT_MIME_TYPE`

Fields inherited from class com.arsdigita.docmgr.ResourceImpl
`PARENT, s_log, versionId`

Fields inherited from class com.arsdigita.versioning.VersionedACSObject
`IS_DELETED, MASTER`

Fields inherited from class com.arsdigita.kernel.ACSObject
`CONTAINER, DEFAULT_DOMAIN_CLASS, DISPLAY_NAME, ID, OBJECT_TYPE`

Fields inherited from interface com.arsdigita.docmgr.Constants
`ACTION, CONTENT, DESCRIPTION, DURATION, FOLDER_ID, IS_FOLDER, LAST_MODIFIED_DATE, MIME_TYPE_LABEL, NAME, OBJECT_ID, PARENT, PARTY_ID, PATH, REPOSITORIES_MOUNTED, SIZE, TEXT_HTML, TEXT_PLAIN, TYPE, USER_ID`

Fields inherited from interface com.arsdigita.docmgr.Resource
`SEPARATOR, SEPARATOR_CHAR`

Constructor Summary
`File(BigDecimal id)` Creates a new File by retrieving it based on ID.
`File(com.arsdigita.persistence.DataObject dataObject)` Creates a new file by retrieving it from the underlying data object.
`File(Folder parent)` Creates an empty file inside a given parent folder.
`File(com.arsdigita.persistence.OID oid)` Creates a new File by retrieving it based on OID.
`File(String objectType)` Creates a file
`File(String name, String description, Folder parent)` Creates a file inside a given parent folder.
`File(String baseDataObjectType, String name, String description, Folder parent)` Creates a file inside a given parent folder.

Method Summary
`protected void` `afterSave()`
`String` `appendExtension(String name)` Append the extension of this file to a given file name.
`protected void` `beforeSave()`
`Resource` `copyTo(String name, Resource parent)` Copies the resource into another location with a new name.
`String` `getBaseDataObjectType()` Returns the pdl object type required for this object.
`String` `getContentType()`
`String` `getDisplayName()` Returns the display name of a file, that is the file name minus any extension if present.
`static String` `getExtension(String name)` Return the extension of a file name, if present.
`InputStream` `getInputStream()` Returns an InputStream suitable for reading the raw content of the file.
`String` `getPrettyContentType()`
`protected Vector` `getPropertyNames()` Return the list of declared property names for a Resource.
`byte[]` `getRawContent()` Returns the raw content of the file as a byte array.
`BigDecimal` `getSize()` Returns the size of the file in bytes.
`static String` `guessContentType(String name, HttpServletRequest request)` Guess the content type for a file by checking the file extension agains the know database of types, or for the existence of a MIME type header in an HttpServletRequest.
`void` `initializeContentType(HttpServletRequest request)` Initialize the content type of a file by looking up a MIME type from the file extension or an optional Content-Type header in an HttpServletRequest.
`boolean` `isFile()` Tests whether this resource is a file.
`boolean` `isFolder()` Tests whether this resource is a folder.
`boolean` `isValidContentType(String contentType)` Returns true if the given content type matches the current content type of a file.
`boolean` `isValidNewName(String name)` Checks for valid characters in a file name and also checks that the name corresponds to a compatible MIME type.
`static File` `retrieveFile(com.arsdigita.persistence.DataObject dataObject)`
`void` `saveNewRevision(File src, String originalName, String versionDesc, HttpServletRequest req)` Saves a new revision of this file.
`void` `setContent(File file, String name, String description)` Sets the content of this resource to a file with a given name and description.
`void` `setContentType(String type)` Sets the MIME type of this file.
`void` `setDataHandler(DataHandler dh)` Provides the mechanism to set this file's content.
`void` `setText(String text)` Convenience method for use with plain text files.

Methods inherited from class com.arsdigita.docmgr.ResourceImpl

`copy, copyTo, copyTo, delete, getCanonicalPath, getCreationDate, getCreationIP, getCreationUser, getDescription, getLastModifiedDate, getLastModifiedIP, getLastModifiedUser, getName, getParent, getParentResourceID, getPath, getResourceID, getResourceID, isAbsolutePath, isRoot, isValidName, isValidPath, retrievePath, setCreationDate, setCreationIP, setCreationUser, setDescription, setLastModifiedDate, setLastModifiedIP, setLastModifiedUser, setName, setParent, toURL`

Methods inherited from class com.arsdigita.versioning.VersionedACSObject
`applyTag, applyUniqueTag, autoPropagateMaster, getMaster, getRolledBackTo, getTransactions, getTransactions, isMaster, isRolledBack, isSubtype, permanentlyDelete, propagateMaster, recordAttributeChange, rollBackTo, rollBackTo, rollForward, save, setMaster, trackChanges`

Methods inherited from class com.arsdigita.kernel.ACSObject
`assertPrivilege, checkPrivilege, doCreateCheck, doWriteCheck, getContainer, getDefaultDomainClass, getID, getSpecificObjectType, getSpecificOID, gimmeContainer, initialize, isContainerModified, setID, setID`

Methods inherited from class com.arsdigita.domain.ObservableDomainObject
`addObserver, getObservers`

Methods inherited from class com.arsdigita.domain.DomainObject
`add, add, addToAssociation, afterDelete, beforeDelete, clear, disconnect, equals, get, getObjectType, getOID, getSession, hashCode, isDeleted, isDisconnected, isModified, isNew, isPropertyModified, isValid, remove, remove, remove, removeFromAssociation, save, set, setAssociation, setAssociation, specializeDataObject, specializeDataObject, toString`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Methods inherited from interface com.arsdigita.docmgr.Resource
`getID, toString`

Field Detail

### BASE_DATA_OBJECT_TYPE

    public static final String BASE_DATA_OBJECT_TYPE

See Also:
  Constant Field Values

### DEFAULT_MIME_TYPE

    public static final String DEFAULT_MIME_TYPE

See Also:
  Constant Field Values

Constructor Detail

### File

    public File(com.arsdigita.persistence.DataObject dataObject)

  Creates a new file by retrieving it from the underlying data object.

Parameters:
  `dataObject` - the dataObject corresponding to this file

### File

    public File(BigDecimal id)
         throws com.arsdigita.domain.DataObjectNotFoundException

  Creates a new File by retrieving it based on ID.

Parameters:
  `id` - - the ID of this file in the database

### File

    public File(com.arsdigita.persistence.OID oid)
         throws com.arsdigita.domain.DataObjectNotFoundException

  Creates a new File by retrieving it based on OID.

Parameters:
  `oid` - - the OID of this file

### File

    public File(String name,
                String description,
                Folder parent)

  Creates a file inside a given parent folder.

Parameters:
  `name` - the name of the File
  `description` - the description of the file contents (may be null)

### File

    public File(String baseDataObjectType,
                String name,
                String description,
                Folder parent)

  Creates a file inside a given parent folder.

Parameters:
  `name` - the name of the File
  `description` - the description of the file contents (may be null)

### File

    public File(Folder parent)

  Creates an empty file inside a given parent folder.

Parameters:
  `parent` - The parent folder

### File

    public File(String objectType)

  Creates a file

Parameters:
  `objectType` - the type of the object

Method Detail

### retrieveFile

    public static File retrieveFile(com.arsdigita.persistence.DataObject dataObject)

### beforeSave

    protected void beforeSave()

  Overrides:
    `beforeSave` in class `ResourceImpl`

### getBaseDataObjectType

    public String getBaseDataObjectType()

  Returns the pdl object type required for this object.

  Overrides:
    `getBaseDataObjectType` in class `ResourceImpl`

### getContentType

    public String getContentType()

  Returns:
    the MIME type of this file as a string, or null if the content type cannot be determined.

### getPrettyContentType

    public String getPrettyContentType()

  Returns:
    the pretty name for the MIME type of the file or null if no content type can be set. For instance, getContentType will return something like "application/msexcel" where this will return "Microsoft Excel document". If the mime type is not registered in the database this this will just return the same value as getContentType()

### setContentType

    public void setContentType(String type)

  Sets the MIME type of this file.

  Parameters:
    `type` - the content type of this file.

### setContent

    public void setContent(File file,
                           String name,
                           String description)
                    throws ResourceException

  Sets the content of this resource to a file with a given name and description.

  Parameters:
    `file` - the file to read content from
    `name` - the name of the file
    `description` - the description of the file
  Throws:
    `ResourceException`

### setText

    public final void setText(String text)

  Convenience method for use with plain text files. Sets the content of the file to a String and sets its MIME type to "text/plain".

### getInputStream

    public InputStream getInputStream()

  Returns an InputStream suitable for reading the raw content of the file.

  Returns:
    an InputStream

### getRawContent

    public byte[] getRawContent()

  Returns the raw content of the file as a byte array. Do not use this method for very large files. Use the {link getInputStream} method instead.

### setDataHandler

    public void setDataHandler(DataHandler dh)
                        throws ResourceException

  Provides the mechanism to set this file's content.

  Parameters:
    `dh` - the DataHandler for this part's content
  Throws:
    `ResourceException`

### getSize

    public BigDecimal getSize()

  Returns the size of the file in bytes.

  Returns:
    the size of the file in bytes, or -1 if the size cannot be computed.

### isFile

    public boolean isFile()

  Description copied from interface: `Resource`
  Tests whether this resource is a file.

  Specified by:
    `isFile` in interface `Resource`
  Specified by:
    `isFile` in class `ResourceImpl`

### isFolder

    public boolean isFolder()

  Description copied from interface: `Resource`
  Tests whether this resource is a folder.

  Specified by:
    `isFolder` in interface `Resource`
  Specified by:
    `isFolder` in class `ResourceImpl`

### copyTo

    public Resource copyTo(String name,
                           Resource parent)

  Description copied from interface: `Resource`
  Copies the resource into another location with a new name.

  Specified by:
    `copyTo` in interface `Resource`
  Specified by:
    `copyTo` in class `ResourceImpl`

### getPropertyNames

    protected Vector getPropertyNames()

  Description copied from class: `ResourceImpl`
  Return the list of declared property names for a Resource. This list only includes the properties that should be duplicated during a copy operation.

  Overrides:
    `getPropertyNames` in class `ResourceImpl`
  Returns:
    the list of directory property names for a File, including those inherited from ResourceImpl.

### initializeContentType

    public void initializeContentType(HttpServletRequest request)
                               throws ContentTypeException

  Initialize the content type of a file by looking up a MIME type from the file extension or an optional Content-Type header in an HttpServletRequest. If these fail the content will be initialized to "application/octet-stream". This only works on a new file

  Parameters:
    `request` - an HttpServletRequest which might contain a Content-Type header, and can be null.
  Throws:
    `ContentTypeException`

### guessContentType

    public static String guessContentType(String name,
                                          HttpServletRequest request)

  Guess the content type for a file by checking the file extension agains the know database of types, or for the existence of a MIME type header in an HttpServletRequest. If these both fail, or if the content type set in the request is not one of the recognized types on the system, return a content type of "application/octet-stream".

  Parameters:
    `name` - the name of a file to be used for an extension-based type lookup
    `request` - an HttpServletRequest which might contain a Content-Type header, and can be null

### getDisplayName

    public String getDisplayName()

  Returns the display name of a file, that is the file name minus any extension if present. An extension is defined as the '.' character followed by one or more non-whitespace characters at the end of the file name. Any file name that begins with '.' will always be returned intact.

### isValidContentType

    public boolean isValidContentType(String contentType)

  Returns true if the given content type matches the current content type of a file. If the file has not yet been saved, any content type is allowed.

### isValidNewName

    public boolean isValidNewName(String name)

  Checks for valid characters in a file name and also checks that the name corresponds to a compatible MIME type. If no extension is supplied and the current file name includes an extension, add that extension to the name before guessing its MIME type.

### appendExtension

    public String appendExtension(String name)

  Append the extension of this file to a given file name. If the given file name already has an extension it will be returned without modification.

### getExtension

    public static String getExtension(String name)

  Return the extension of a file name, if present. Otherwise return an empty string.

### afterSave

    protected void afterSave()

  Overrides:
    `afterSave` in class `ResourceImpl`

### saveNewRevision

    public void saveNewRevision(File src,
                                String originalName,
                                String versionDesc,
                                HttpServletRequest req)

  Saves a new revision of this file.

  Parameters:
    `src` - The source file to upload to the database.
    `originalName` - The original name of the file. The servlet container may not return the same file extension. For example, tomcat will return some random .tmp file, which will cause mime type checking to fail.
    `versionDesc` - The description of this version of the file.
    `req` - Optional Htttp request for guessing the file's mime-type.

Copyright (c) 2006 Red Hat, Inc. Corporation. All Rights Reserved. Generated at June 1 2006:1113 UTC