Ignore:
Timestamp:
2011-08-15T13:42:41+12:00 (13 years ago)
Author:
sjm84
Message:

Added comments and fixed an error that was somehow introduced

File:
1 edited

Legend:

Unmodified
Added
Removed

  • main/trunk/greenstone3/src/java/org/greenstone/gsdl3/util/GSDocumentModel.java

    r24393 r24409  
    2525import org.w3c.dom.NodeList;
    2626
    27 import com.oopsconsultancy.xmltask.InsertAction.Position;
    28 
    2927public class GSDocumentModel
    3028{
    … …  
    3331    protected static final String ARCHIVEINFDOC = "archiveinf-doc";
    3432
    35     //Set section operations
     33    //Set operations
    3634    public static final int OPERATION_REPLACE = 1;
    3735    public static final int OPERATION_INSERT_BEFORE = 2;
    … …  
    114112    }
    115113
     114    /**
     115     * Can be used to create a document or create a section of a document
     116     *
     117     * @param oid
     118     *            is the identifier of the document/section to create.
     119     * @param collection
     120     *            is the collection we want to create the document/section in.
     121     */
    116122    public void documentCreate(String oid, String collection, String lang, String uid)
    117123    {
    … …  
    172178    }
    173179
     180    /**
     181     * Can be used to delete a document or section
     182     *
     183     * @param oid
     184     *            is the identifier of the document/section to delete.
     185     * @param collection
     186     *            is the collection to delete the document/section from.
     187     */
    174188    public void documentDelete(String oid, String collection, String lang, String uid)
    175189    {
    … …  
    218232    }
    219233
     234    /**
     235     * Can be used to copy a document or section from one place to another.
     236     *
     237     * @param oid
     238     *            is the identifier of the document/section that is to be
     239     *            copied.
     240     * @param collection
     241     *            is the collection the source document resides in.
     242     * @param newOID
     243     *            is the new identifier for the document/section (it cannot
     244     *            already exist).
     245     * @param newCollection
     246     *            is the collection the new document/section will be copied to.
     247     *            If this is null then the collection parameter will be used
     248     *            instead.
     249     */
    220250    public void documentDuplicate(String oid, String collection, String newOID, String newCollection, String lang, String uid)
    221251    {
    … …  
    339369    }
    340370
    341     //TODO: Change return type to something else
    342     public void documentGetInformation(String oid, String collection, String[] requestedInfo, String lang, String uid)
     371    /**
     372     * Can be used to acquire information about a given document or section.
     373     *
     374     * @param oid
     375     *            is the identifier of the document or section.
     376     * @param collection
     377     *            is the collection the document or section resides in.
     378     * @param requestedInfo
     379     *            is an array containing the various requests.
     380     * @return This returns an array containing the requested information.
     381     */
     382    public String[] documentGetInformation(String oid, String collection, String[] requestedInfo, String lang, String uid)
    343383    {
    344384        if ((_errorStatus = checkOIDandCollection(oid, collection, lang, uid)) != NO_ERROR)
    345385        {
    346             return;
     386            return null;
    347387        }
    348388
    … …  
    354394            //-Metadata keys
    355395        }
    356     }
    357 
     396        //TODO: Implement
     397        return null;
     398    }
     399
     400    /**
     401     * Can be used to move a document or section from one place to another.
     402     *
     403     * @param oid
     404     *            is the identifier of the document/section to move.
     405     * @param collection
     406     *            is the collection the source document resides in.
     407     * @param newOID
     408     *            is the new identifer for the moved document.
     409     * @param newCollection
     410     *            is the collection the new document/section will be moved to.
     411     *            If this is null then the collection parameter will be used
     412     *            instead.
     413     */
    358414    public void documentMove(String oid, String collection, String newOID, String newCollection, String lang, String uid)
    359415    {
    … …  
    372428    }
    373429
     430    /**
     431     * Can be used to merge two parts of a document together. The sections must
     432     * be in the same document at the same level (e.g. D11.1.2 and D11.1.3) or a
     433     * section and it's parent (e.g. D11.1.2 and D11.1). Also, the destination
     434     * section cannot have any child sections.
     435     *
     436     * @param oid
     437     *            the identifier of the section that is to be merged.
     438     * @param collection
     439     *            the collection the section resides in.
     440     * @param mergeOID
     441     *            the identifier of the section that the source section will be
     442     *            merged into.
     443     */
    374444    public void documentMerge(String oid, String collection, String mergeOID, String lang, String uid)
    375445    {
    … …  
    483553    }
    484554
     555    /**
     556     * Can be used to split a section into two sections (e.g. D11.2.1 will
     557     * become D11.2.1 and D11.2.2). Any child section will belong to the second
     558     * section (D11.2.2 in the example).
     559     *
     560     * @param oid
     561     *            is the identifer of the section to be split.
     562     * @param collection
     563     *            is the collection the section resides in.
     564     * @param splitPoint
     565     *            is the point in the text we want to split at.
     566     */
    485567    public void documentSplit(String oid, String collection, int splitPoint, String lang, String uid)
    486568    {
    … …  
    551633    }
    552634
     635    /**
     636     * Creates a basic doc.xml file with minimal contents.
     637     *
     638     * @param oid
     639     *            is the identifier of the document to be created.
     640     * @param collection
     641     *            is the collection the new document will reside in.
     642     */
    553643    public void documentXMLCreateDocXML(String oid, String collection, String lang, String uid)
    554644    {
    … …  
    587677    }
    588678
     679    /**
     680     * Gets a metadata value from a document or section.
     681     *
     682     * @param oid
     683     *            is the identifier of the section or document to get metadata
     684     *            from.
     685     * @param collection
     686     *            is the collection the section or document resides in.
     687     * @param metadataName
     688     *            is the name of metadata to retrieve
     689     * @return an array of metadata elements containing the resquested metadata
     690     */
    589691    public ArrayList<Element> documentXMLGetMetadata(String oid, String collection, String metadataName, String lang, String uid)
    590692    {
    … …  
    609711    }
    610712
     713    /**
     714     *
     715     * @param oid
     716     *            is the identifier of the document or section that is to have
     717     *            it's metadata set.
     718     * @param collection
     719     *            is the collection the document/section resides in.
     720     * @param metadataName
     721     *            is the name of the metadata value that is to be set.
     722     * @param newMetadataValue
     723     *            is the new value of the metadata.
     724     * @param position
     725     *            specifies the position of the value to set.
     726     * @param operation
     727     *            can be one of OPERATION_REPLACE, OPERATION_INSERT_BEFORE,
     728     *            OPERATION_INSERT_AFTER or OPERATION_APPEND.
     729     */
    611730    public void documentXMLSetMetadata(String oid, String collection, String metadataName, String newMetadataValue, int position, int operation, String lang, String uid)
    612731    {
    … …  
    687806    }
    688807
     808    /**
     809     * Can be used to delete metadata at a specific position in a document or
     810     * section (such as the third author of a document).
     811     *
     812     * @param oid
     813     *            is the identifier of the document/section to delete metadata
     814     *            from.
     815     * @param collection
     816     *            is the collection the document resides in.
     817     * @param metadataName
     818     *            is the name of the metadata that is to have an item deleted.
     819     * @param position
     820     *            is position of the item that is to be deleted.
     821     */
    689822    public void documentXMLDeleteMetadata(String oid, String collection, String metadataName, int position, String lang, String uid)
    690823    {
    … …  
    714847    }
    715848
     849    /**
     850     * Can be used to delete all the metadata with a specific name from a
     851     * document or section (e.g. all of the authors).
     852     *
     853     * @param oid
     854     *            is the identifier of the document or section to delete the
     855     *            metadata from.
     856     * @param collection
     857     *            is the collection the document resides in.
     858     * @param metadataName
     859     *            is the name of the metadata to delete.
     860     */
    716861    public void documentXMLDeleteMetadata(String oid, String collection, String metadataName, String lang, String uid)
    717862    {
    … …  
    741886    }
    742887
     888    /**
     889     * Can be used to replace a specific metadata item of a given name, given
     890     * it's value.
     891     *
     892     * @param oid
     893     *            is the document/section of the metadata that is to be
     894     *            replaced.
     895     * @param collection
     896     *            is the collection the document resides in.
     897     * @param metadataName
     898     *            is the name of the metadata to be replaced.
     899     * @param oldMetadataValue
     900     *            is the old value of the metadata (the value that will be
     901     *            replaced).
     902     * @param newMetadataValue
     903     *            is the new value of the metadata that will replace the old
     904     *            value.
     905     */
    743906    public void documentXMLReplaceMetadata(String oid, String collection, String metadataName, String oldMetadataValue, String newMetadataValue, String lang, String uid)
    744907    {
    … …  
    789952    }
    790953
     954    /**
     955     * Can be used to create a blank section.
     956     *
     957     * @param oid
     958     *            is the identifier of the section to be created.
     959     * @param collection
     960     *            is the collection the document resides in.
     961     */
    791962    public void documentXMLCreateSection(String oid, String collection, String lang, String uid)
    792963    {
    … …  
    8781049    }
    8791050
     1051    /**
     1052     * Can be used to delete an entire section.
     1053     *
     1054     * @param oid
     1055     *            is the identifier of the section to be deleted.
     1056     * @param collection
     1057     *            is the collection the document resides in.
     1058     */
    8801059    public void documentXMLDeleteSection(String oid, String collection, String lang, String uid)
    8811060    {
    … …  
    9081087    }
    9091088
     1089    /**
     1090     * Can be used to get a section from a document.
     1091     *
     1092     * @param oid
     1093     *            is the identifier of the section to get.
     1094     * @param collection
     1095     *            is the collection the document resides in.
     1096     * @return the requested section.
     1097     */
    9101098    public Element documentXMLGetSection(String oid, String collection, String lang, String uid)
    9111099    {
    … …  
    9411129    }
    9421130
    943     public void documentXMLSetSection(String oid, String collection, Element newSection, int op, String lang, String uid)
     1131    /**
     1132     * Can be used to set an OID to the given section element.
     1133     *
     1134     * @param oid
     1135     *            is the identifier of the section to be set.
     1136     * @param collection
     1137     *            is the collection the section will reside in.
     1138     * @param newSection
     1139     *            is the new section element.
     1140     * @param operation
     1141     *            can be one of OPERATION_REPLACE, OPERATION_INSERT_BEFORE,
     1142     *            OPERATION_INSERT_AFTER or OPERATION_APPEND.
     1143     */
     1144    public void documentXMLSetSection(String oid, String collection, Element newSection, int operation, String lang, String uid)
    9441145    {
    9451146        if ((_errorStatus = checkOIDandCollection(oid, collection, lang, uid)) != NO_ERROR)
    … …  
    9731174        Element importedSection = (Element) docXML.importNode(newSection, true);
    9741175
    975         if (op == OPERATION_APPEND)
     1176        if (operation == OPERATION_APPEND)
    9761177        {
    9771178            existingSection.appendChild(importedSection);
    … …  
    9851186            importedSection.removeAttribute(GSXML.COLLECTION_ATT);
    9861187
    987             if (op == OPERATION_INSERT_BEFORE || op == OPERATION_REPLACE)
     1188            if (operation == OPERATION_INSERT_BEFORE || operation == OPERATION_REPLACE)
    9881189            {
    9891190                sectionParent.insertBefore(importedSection, existingSection);
    9901191            }
    991             else if (op == OPERATION_INSERT_AFTER)
     1192            else if (operation == OPERATION_INSERT_AFTER)
    9921193            {
    9931194                Element sibling = (Element) existingSection.getNextSibling();
    … …  
    10021203            }
    10031204
    1004             if (op == OPERATION_REPLACE)
     1205            if (operation == OPERATION_REPLACE)
    10051206            {
    10061207                sectionParent.removeChild(existingSection);
    … …  
    10161217    }
    10171218
     1219    /**
     1220     * Gets the text of a given section as a string.
     1221     *
     1222     * @param oid
     1223     *            is the identifier of the section to get the text from.
     1224     * @param collection
     1225     *            is the collection the document resides in.
     1226     * @return the text from the section.
     1227     */
    10181228    public String documentXMLGetText(String oid, String collection, String lang, String uid)
    10191229    {
    … …  
    10611271    }
    10621272
     1273    /**
     1274     * Sets the text of a given section using an element.
     1275     *
     1276     * @param oid
     1277     *            is the identifier of the section to set the text of.
     1278     * @param collection
     1279     *            is the collection the document resides in.
     1280     * @param newContent
     1281     *            is the new content element for the section.
     1282     */
    10631283    public void documentXMLSetText(String oid, String collection, Element newContent, String lang, String uid)
    10641284    {
    … …  
    11201340    }
    11211341
     1342    /**
     1343     * Sets the text of a given section using a string.
     1344     *
     1345     * @param oid
     1346     *            is the identifier of the section to set the text of.
     1347     * @param collection
     1348     *            is the collection the document resides in.
     1349     * @param newContent
     1350     *            is the new text for the section.
     1351     */
    11221352    public void documentXMLSetText(String oid, String collection, String newContent, String lang, String uid)
    11231353    {
    … …  
    11801410    }
    11811411
     1412    /**
     1413     * Can be used to get the file path of the doc.xml file containing the given
     1414     * OID.
     1415     *
     1416     * @param oid
     1417     *            is the identifier of the document/section to get the doc.xml
     1418     *            of.
     1419     * @param collection
     1420     *            is the collection the document resides in.
     1421     * @return the file path to the doc.xml file.
     1422     */
    11821423    public String archiveGetDocumentFilePath(String oid, String collection, String lang, String uid)
    11831424    {
    … …  
    12051446    }
    12061447
     1448    /**
     1449     * Can be used to find the document that a specific source file is used in.
     1450     *
     1451     * @param srcFile
     1452     *            is the name of the source file.
     1453     * @param collection
     1454     *            is the collection the source file resides in.
     1455     * @return the OID of the document that the source file is used in.
     1456     */
    12071457    public String archiveGetSourceFileOID(String srcFile, String collection, String lang, String uid)
    12081458    {
    … …  
    12291479    }
    12301480
     1481    /**
     1482     * Checks to see if a document or section at a given OID exists.
     1483     *
     1484     * @param oid
     1485     *            is the identifier of the document/section to check.
     1486     * @param collection
     1487     *            is the collection to search in.
     1488     * @return true if the document/section exists, false otherwise.
     1489     */
    12311490    public boolean archiveCheckDocumentOrSectionExists(String oid, String collection, String lang, String uid)
    12321491    {
    … …  
    12701529    }
    12711530
     1531    /**
     1532     * Can be used to write a series of entries to the document database.
     1533     *
     1534     * @param oid
     1535     *            is the key that the entries will be written to.
     1536     * @param collection
     1537     *            is the collection whose database will be written to.
     1538     * @param infoList
     1539     *            is the list of entries to write.
     1540     */
    12721541    public void archiveWriteEntryToDatabase(String oid, String collection, HashMap<String, ArrayList<String>> infoList, String lang, String uid)
    12731542    {
    … …  
    13041573    }
    13051574
     1575    /**
     1576     * Can be used to remove an entry from the document database.
     1577     *
     1578     * @param oid
     1579     *            is the key of the entry to erase.
     1580     * @param collection
     1581     *            is the collection whose database will have the entry removed.
     1582     */
    13061583    public void archiveRemoveEntryFromDatabase(String oid, String collection, String lang, String uid)
    13071584    {
    … …  
    13281605    }
    13291606
     1607    /**
     1608     * Gets the list of associated files for a given document.
     1609     * @param oid is the identifier that will be used to search for associated documents.
     1610     * @param collection is the collection whose database will be searched.
     1611     * @return the list of associated files.
     1612     */
    13301613    public ArrayList<String> archiveGetAssociatedImportFiles(String oid, String collection, String lang, String uid)
    13311614    {
Note: See TracChangeset for help on using the changeset viewer.