toFileName.
+ *
+ *
+ * If the toFileName is null, file name use original file name instead
+ * and file save path will be system temporary directory.
+ *
+ * @param uuid
+ * @param toFileName
+ * file name to save. Using the original file name instead if null value given.
+ * @throws ItemNotFoundException
+ * @throws RepositoryCheckedException
+ * @throws IOException
+ */
+ public void saveFile(Long uuid, String toFileName)
+ throws ItemNotFoundException, RepositoryCheckedException, IOException;
+}
\ No newline at end of file
Index: lams_common/src/java/org/lamsfoundation/lams/contentrepository/client/ToolContentHandler.java
===================================================================
diff -u
--- lams_common/src/java/org/lamsfoundation/lams/contentrepository/client/ToolContentHandler.java (revision 0)
+++ lams_common/src/java/org/lamsfoundation/lams/contentrepository/client/ToolContentHandler.java (revision 46fe95e04d6fbe8fec9e41f054a711e23c1e064c)
@@ -0,0 +1,396 @@
+/****************************************************************
+ * Copyright (C) 2005 LAMS Foundation (http://lamsfoundation.org)
+ * =============================================================
+ * License Information: http://lamsfoundation.org/licensing/lams/2.0/
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2.0
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
+ * USA
+ *
+ * http://www.gnu.org/licenses/gpl.txt
+ * ****************************************************************
+ */
+
+
+package org.lamsfoundation.lams.contentrepository.client;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+import org.apache.log4j.Logger;
+import org.lamsfoundation.lams.contentrepository.ICredentials;
+import org.lamsfoundation.lams.contentrepository.ITicket;
+import org.lamsfoundation.lams.contentrepository.NodeKey;
+import org.lamsfoundation.lams.contentrepository.exception.AccessDeniedException;
+import org.lamsfoundation.lams.contentrepository.exception.FileException;
+import org.lamsfoundation.lams.contentrepository.exception.InvalidParameterException;
+import org.lamsfoundation.lams.contentrepository.exception.ItemNotFoundException;
+import org.lamsfoundation.lams.contentrepository.exception.RepositoryCheckedException;
+import org.lamsfoundation.lams.contentrepository.service.IRepositoryService;
+import org.lamsfoundation.lams.contentrepository.service.SimpleCredentials;
+
+/**
+ * Handles the connection to the content repository, and allows a file
+ * to be stored and retrieved.
+ *
+ * It can be used by LAMS tools to do the handling the files. + *
+ * It is a very simple client, in that + * it only handles files (and not packages) and will not keep versions + * of files - to do a new version of a file, the old version is deleted + * and the new version added. + *
+ * To use this class: + *
+ * <bean id="blahToolContentHandler" class="your class name here"> + * <property name="repositoryService"> <ref bean="repositoryService"/</property> + * </bean> + *+ * + * + * You do not need to include repositoryService as a instance variable + * in your own class as it is already defined in the ToolContentHandler abstract class. + *
+ * The methods you are likely to use are: + *
+ * NodeKey nodeKey = handler.uploadFile(istream, fileName, fileMimeType);+ *
+ * Long uuid = nodeKey.getUuid();
+ * IVersionedNode node = handler.getFileNode(uuid);
+ * IStream fileStreamToWriteSomewhere = node.getFile());
+ *
+ * Please read the javadoc on each method for more information on the exceptions thrown + * and on the mandatory parameters. + *
+ * If you want to see this class used, have a look at the test code in org.lamsfoundation.lams.contentrepository.client + * in the test/java area. + *
+ * You may be wondering why we don't make the workspaceName, user, id, etc + * parameters in the Spring file, rather than creating a concrete class. Using + * the Spring file would be easier, but then the id (equivalent to passsword) + * is easier to hack. The id is a char[], rather than a String for + * security. If you don't care that your tool's id is stored as a String + * then you can include it in your Spring file. + * + * @author conradb, Fiona Malikoff + */ +public abstract class ToolContentHandler implements IToolContentHandler { + + private IRepositoryService repositoryService; + private ITicket ticket; + + protected Logger log = Logger.getLogger(ToolContentHandler.class.getName()); + + /** + * @return Returns the repositoryWorkspaceName. + */ + @Override + public abstract String getRepositoryWorkspaceName(); + + /** + * @return Returns the repositoryUser. + */ + @Override + public abstract String getRepositoryUser(); + + /** + * @return Returns the repository identification string. This is the + * "password" field the credential. + */ + @Override + public abstract char[] getRepositoryId(); + + @Override + public ITicket getTicket(boolean forceLogin) throws RepositoryCheckedException { + ICredentials cred = null; + boolean doLogin = ticket == null || forceLogin; + if (!doLogin) { + // make sure workspace exists - sometimes it does not get created when creating a ticket + cred = new SimpleCredentials(getRepositoryUser(), getRepositoryId()); + doLogin = !repositoryService.workspaceExists(cred, getRepositoryWorkspaceName()); + } + if (doLogin) { + if (cred == null) { + cred = new SimpleCredentials(getRepositoryUser(), getRepositoryId()); + } + ticket = repositoryService.login(cred, getRepositoryWorkspaceName()); + } + return ticket; + } + + @Override + public NodeKey uploadFile(InputStream stream, String fileName, String mimeType) + throws RepositoryCheckedException, InvalidParameterException, RepositoryCheckedException { + NodeKey nodeKey = null; + try { + try { + nodeKey = repositoryService.addFileItem(getTicket(false), stream, fileName, mimeType, null); + } catch (AccessDeniedException e) { + log.warn("Unable to access repository to add file " + fileName + "AccessDeniedException: " + + e.getMessage() + " Retrying login."); + nodeKey = repositoryService.addFileItem(getTicket(true), stream, fileName, mimeType, null); + } + + } catch (RepositoryCheckedException e2) { + log.warn("Unable to to uploadFile" + fileName + "Repository Exception: " + e2.getMessage() + + " Retry not possible."); + throw e2; + } + + return nodeKey; + } + + @Override + public NodeKey updateFile(Long uuid, InputStream stream, String fileName, String mimeType) + throws RepositoryCheckedException, InvalidParameterException, RepositoryCheckedException { + NodeKey nodeKey = null; + try { + try { + nodeKey = repositoryService.updateFileItem(getTicket(false), uuid, fileName, stream, mimeType, null); + } catch (AccessDeniedException e) { + log.warn("Unable to access repository to add file " + fileName + "AccessDeniedException: " + + e.getMessage() + " Retrying login."); + nodeKey = repositoryService.updateFileItem(getTicket(true), uuid, fileName, stream, mimeType, null); + } + + } catch (RepositoryCheckedException e2) { + log.warn("Unable to to updateFile" + fileName + "Repository Exception: " + e2.getMessage() + + " Retry not possible."); + throw e2; + } + + return nodeKey; + } + + /** + * TODO To be removed from the system and replaced with the call with the user id. + */ + @Override + public NodeKey uploadPackage(String dirPath, String startFile) + throws RepositoryCheckedException, InvalidParameterException, RepositoryCheckedException { + log.error( + "uploadPackage(String dirPath, String startFile) to be removed - it sets the owner of files in the content repository to 1. Some tool needs to be updated."); + return uploadPackage(dirPath, startFile, new Integer(1)); + } + + /** + * Save a directory of files in the content repository. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param dirPath + * directory path containing files - mandatory + * @param startFile + * relative path of initial file - optional + * @return nodeKey (uuid and version) + * @throws InvalidParameterException + * One of the mandatory parameters is missing. + * @throws FileException + * An error occured writing the files to disk. + * @throws RepositoryCheckedException + * Some other error occured. + */ + private NodeKey uploadPackage(String dirPath, String startFile, Integer userId) + throws RepositoryCheckedException, InvalidParameterException, RepositoryCheckedException { + if (dirPath == null) { + throw new InvalidParameterException( + "uploadFile: dirPath parameter empty. Directory containing files must be supplied"); + } + + NodeKey nodeKey = null; + try { + try { + nodeKey = repositoryService.addPackageItem(getTicket(false), dirPath, startFile, null); + } catch (AccessDeniedException e) { + log.warn("Unable to access repository to add directory of files. AccessDeniedException: " + + e.getMessage() + " Retrying login."); + nodeKey = repositoryService.addPackageItem(getTicket(true), dirPath, startFile, null); + } + + } catch (RepositoryCheckedException e2) { + log.warn("Unable to access repository to add directory of files. Repository Exception: " + e2.getMessage() + + " Retry not possible."); + throw e2; + } + + return nodeKey; + } + + @Override + public void saveFile(Long uuid, String toFileName) + throws ItemNotFoundException, RepositoryCheckedException, IOException { + try { + try { + repositoryService.saveFile(getTicket(false), uuid, null, toFileName); + } catch (AccessDeniedException e) { + log.warn("Unable to access repository to add copy node " + uuid + "AccessDeniedException: " + + e.getMessage() + " Retrying login."); + repositoryService.saveFile(getTicket(false), uuid, null, toFileName); + } + } catch (ItemNotFoundException e) { + log.warn("Unable to to save node " + uuid + " as the node cannot be found. Repository Exception: " + + e.getMessage() + " Retry not possible."); + throw e; + } catch (RepositoryCheckedException e) { + log.warn("Unable to to save node " + uuid + "Repository Exception: " + e.getMessage() + + " Retry not possible."); + throw e; + } + } + + /** + * TODO To be removed from the system and replaced with the call with the user id. + */ + @Override + public NodeKey copyFile(Long uuid) throws ItemNotFoundException, RepositoryCheckedException { + log.error( + "copyFile(Long uuid) to be removed - it sets the owner of files in the content repository to 1. Some tool needs to be updated."); + return copyFile(uuid, new Integer(1)); + } + + /** + * Copy an entry in the content repository. + * + * @param uuid + * id of the file node. Mandatory + * @throws ItemNotFoundException + * Node to copy cannot be found + * @throws RepositoryCheckedException + * Some other error occured. + */ + private NodeKey copyFile(Long uuid, Integer userId) throws ItemNotFoundException, RepositoryCheckedException { + NodeKey nodeKey = null; + try { + try { + nodeKey = repositoryService.copyNodeVersion(getTicket(false), uuid, null); + } catch (AccessDeniedException e) { + log.warn("Unable to access repository to add copy node " + uuid + "AccessDeniedException: " + + e.getMessage() + " Retrying login."); + nodeKey = repositoryService.copyNodeVersion(getTicket(true), uuid, null); + } + } catch (ItemNotFoundException e) { + log.warn("Unable to to copy node " + uuid + " as the node cannot be found. Repository Exception: " + + e.getMessage() + " Retry not possible."); + throw e; + } catch (RepositoryCheckedException e) { + log.warn("Unable to to copy node " + uuid + "Repository Exception: " + e.getMessage() + + " Retry not possible."); + throw e; + } + return nodeKey; + } + + @Override + public void deleteFile(Long uuid) throws InvalidParameterException, RepositoryCheckedException { + try { + try { + repositoryService.deleteNode(getTicket(false), uuid); + } catch (AccessDeniedException e) { + log.warn("Unable to access repository to delete file id" + uuid + "AccessDeniedException: " + + e.getMessage() + " Retrying login."); + repositoryService.deleteNode(getTicket(true), uuid); + } + } catch (ItemNotFoundException e1) { + // didn't exist so don't need to delete. Ignore problem. + } catch (RepositoryCheckedException e2) { + log.error("Unable delete file id" + uuid + "Repository Exception: " + e2.getMessage() + + " Retry not possible."); + throw e2; + } + } + + @Override + public InputStream getFileInputStream(Long uuid) + throws ItemNotFoundException, FileException, RepositoryCheckedException { + try { + try { + return repositoryService.getFileItem(getTicket(false), uuid, null).getFile(); + } catch (AccessDeniedException e) { + log.warn("Unable to access repository to get file id" + uuid + "AccessDeniedException: " + + e.getMessage() + " Retrying login."); + return repositoryService.getFileItem(getTicket(true), uuid, null).getFile(); + } + } catch (RepositoryCheckedException e2) { + log.warn("Unable to to get file id" + uuid + "Repository Exception: " + e2.getMessage() + + " Retry not possible."); + throw e2; + } + } + +/* + * protected File getFile(String fileName, InputStream is) throws FileNotFoundException, Exception { + * InputStream in = new BufferedInputStream(is, 500); + * File file = new File(fileName); + * OutputStream out = new BufferedOutputStream(new FileOutputStream(file), 500); + * int bytes; + * while ((bytes = in.available()) > 0) { + * byte[] byteArray = new byte[bytes]; + * in.read(byteArray); + * out.write(byteArray); + * } + * in.close(); + * out.close(); + * out.flush(); + * return file; + * } + * + * protected byte[] getBytes(File file) throws FileNotFoundException, Exception { + * byte[] byteArray = new byte[(int) file.length()]; + * FileInputStream stream = new FileInputStream(file); + * stream.read(byteArray); + * stream.close(); + * return byteArray; + * } + */ + + /* *** Required for Spring bean creation **************************/ + + /** + * @return Returns the repositoryService. + */ + @Override + public IRepositoryService getRepositoryService() { + return repositoryService; + } + + /** + * @param repositoryService + * The repositoryService to set. + */ + public void setRepositoryService(IRepositoryService repositoryService) { + this.repositoryService = repositoryService; + } +} Index: lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/FileException.java =================================================================== diff -u --- lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/FileException.java (revision 0) +++ lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/FileException.java (revision 46fe95e04d6fbe8fec9e41f054a711e23c1e064c) @@ -0,0 +1,74 @@ +/**************************************************************** + * Copyright (C) 2005 LAMS Foundation (http://lamsfoundation.org) + * ============================================================= + * License Information: http://lamsfoundation.org/licensing/lams/2.0/ + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2.0 + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 + * USA + * + * http://www.gnu.org/licenses/gpl.txt + * **************************************************************** + */ + + +package org.lamsfoundation.lams.contentrepository.exception; + +/** + * Some error was generated reading or writing the files + * to disk. + */ +public class FileException extends RepositoryCheckedException { + /** + * Constructs a new instance of this class. + */ + public FileException() { + this("File error occured."); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure cause. + * + * @param s + * description + */ + public FileException(String s) { + super(s); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure and a root throwable. + * + * @param s + * description + * @param cause + * root throwable cause + */ + public FileException(String s, Throwable cause) { + super(s, cause); + + } + + /** + * Constructs a new instance of this class given a root throwable. + * + * @param cause + * root failure cause + */ + public FileException(Throwable cause) { + this("File error occured.", cause); + } + +} Index: lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/InvalidParameterException.java =================================================================== diff -u --- lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/InvalidParameterException.java (revision 0) +++ lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/InvalidParameterException.java (revision 46fe95e04d6fbe8fec9e41f054a711e23c1e064c) @@ -0,0 +1,73 @@ +/**************************************************************** + * Copyright (C) 2005 LAMS Foundation (http://lamsfoundation.org) + * ============================================================= + * License Information: http://lamsfoundation.org/licensing/lams/2.0/ + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2.0 + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 + * USA + * + * http://www.gnu.org/licenses/gpl.txt + * **************************************************************** + */ + + +package org.lamsfoundation.lams.contentrepository.exception; + +/** + * Generic exception thrown whenever a parameter is missing. + */ +public class InvalidParameterException extends RepositoryCheckedException { + /** + * Constructs a new instance of this class. + */ + public InvalidParameterException() { + this("A required parameter is null."); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure cause. + * + * @param s + * description + */ + public InvalidParameterException(String s) { + super(s); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure and a root throwable. + * + * @param s + * description + * @param cause + * root throwable cause + */ + public InvalidParameterException(String s, Throwable cause) { + super(s, cause); + + } + + /** + * Constructs a new instance of this class given a root throwable. + * + * @param cause + * root failure cause + */ + public InvalidParameterException(Throwable cause) { + this("A required parameter is null.", cause); + } + +} Index: lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/ItemNotFoundException.java =================================================================== diff -u --- lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/ItemNotFoundException.java (revision 0) +++ lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/ItemNotFoundException.java (revision 46fe95e04d6fbe8fec9e41f054a711e23c1e064c) @@ -0,0 +1,74 @@ +/**************************************************************** + * Copyright (C) 2005 LAMS Foundation (http://lamsfoundation.org) + * ============================================================= + * License Information: http://lamsfoundation.org/licensing/lams/2.0/ + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2.0 + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 + * USA + * + * http://www.gnu.org/licenses/gpl.txt + * **************************************************************** + */ + + +package org.lamsfoundation.lams.contentrepository.exception; + +/** + * Item requested does not exist. + */ +public class ItemNotFoundException extends RepositoryCheckedException { + + /** + * Constructs a new instance of this class. + */ + public ItemNotFoundException() { + this("Item requested does not exist."); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure cause. + * + * @param s + * description + */ + public ItemNotFoundException(String s) { + super(s); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure and a root throwable. + * + * @param s + * description + * @param cause + * root throwable cause + */ + public ItemNotFoundException(String s, Throwable cause) { + super(s, cause); + + } + + /** + * Constructs a new instance of this class given a root throwable. + * + * @param cause + * root failure cause + */ + public ItemNotFoundException(Throwable cause) { + this("Item requested does not exist.", cause); + } + +} Index: lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/RepositoryCheckedException.java =================================================================== diff -u --- lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/RepositoryCheckedException.java (revision 0) +++ lams_common/src/java/org/lamsfoundation/lams/contentrepository/exception/RepositoryCheckedException.java (revision 46fe95e04d6fbe8fec9e41f054a711e23c1e064c) @@ -0,0 +1,93 @@ +/**************************************************************** + * Copyright (C) 2005 LAMS Foundation (http://lamsfoundation.org) + * ============================================================= + * License Information: http://lamsfoundation.org/licensing/lams/2.0/ + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2.0 + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 + * USA + * + * http://www.gnu.org/licenses/gpl.txt + * **************************************************************** + */ + + +package org.lamsfoundation.lams.contentrepository.exception; + +/** + * Main exception thrown by content repository classes. All exceptions thrown by the content + * repository (except RepositoryRuntimeException) are based on this class, so calling code + * can catch this exception and catch all of the repository exceptions, if it doesn't want to + * catch particular exceptions. + * + * @see RepositoryRuntimeException + */ +public class RepositoryCheckedException extends Exception { + + /** + * Constructs a new instance of this class. + */ + public RepositoryCheckedException() { + this("Content Repository Error."); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure cause. + * + * @param s + * description + */ + public RepositoryCheckedException(String s) { + super(s); + } + + /** + * Constructs a new instance of this class given a message describing the + * failure and a root throwable. + * + * @param s + * description + * @param cause + * root throwable cause + */ + public RepositoryCheckedException(String s, Throwable cause) { + super(s, cause); + + } + + /** + * Constructs a new instance of this class given a root throwable. + * + * @param cause + * root failure cause + */ + public RepositoryCheckedException(Throwable cause) { + this("Content Repository Error.", cause); + } + + @Override + public String getMessage() { + + String s1 = super.getMessage(); + if (s1 == null) { + s1 = ""; + } + + Throwable cause = getCause(); + String s2 = cause != null ? cause.getMessage() : null; + return s2 != null ? s1 + ":" + s2 : s1; + + } + +} Index: lams_common/src/java/org/lamsfoundation/lams/contentrepository/service/IRepositoryService.java =================================================================== diff -u --- lams_common/src/java/org/lamsfoundation/lams/contentrepository/service/IRepositoryService.java (revision 0) +++ lams_common/src/java/org/lamsfoundation/lams/contentrepository/service/IRepositoryService.java (revision 46fe95e04d6fbe8fec9e41f054a711e23c1e064c) @@ -0,0 +1,488 @@ +/**************************************************************** + * Copyright (C) 2005 LAMS Foundation (http://lamsfoundation.org) + * ============================================================= + * License Information: http://lamsfoundation.org/licensing/lams/2.0/ + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2.0 + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 + * USA + * + * http://www.gnu.org/licenses/gpl.txt + * **************************************************************** + */ + +package org.lamsfoundation.lams.contentrepository.service; + +import java.io.IOException; +import java.io.InputStream; +import java.util.List; +import java.util.SortedMap; +import java.util.SortedSet; + +import org.lamsfoundation.lams.contentrepository.CrWorkspace; +import org.lamsfoundation.lams.contentrepository.ICredentials; +import org.lamsfoundation.lams.contentrepository.ITicket; +import org.lamsfoundation.lams.contentrepository.IVersionedNode; +import org.lamsfoundation.lams.contentrepository.NodeKey; +import org.lamsfoundation.lams.contentrepository.exception.AccessDeniedException; +import org.lamsfoundation.lams.contentrepository.exception.FileException; +import org.lamsfoundation.lams.contentrepository.exception.InvalidParameterException; +import org.lamsfoundation.lams.contentrepository.exception.ItemExistsException; +import org.lamsfoundation.lams.contentrepository.exception.ItemNotFoundException; +import org.lamsfoundation.lams.contentrepository.exception.LoginException; +import org.lamsfoundation.lams.contentrepository.exception.RepositoryCheckedException; +import org.lamsfoundation.lams.contentrepository.exception.RepositoryRuntimeException; +import org.lamsfoundation.lams.contentrepository.exception.ValidationException; +import org.lamsfoundation.lams.contentrepository.exception.ValueFormatException; +import org.lamsfoundation.lams.contentrepository.exception.WorkspaceNotFoundException; + +/** + * Tool access to the repository. + *
+ * Runtime exceptions will trigger the transaction to be marked for rollback. + * Checked exceptions will NOT trigger the transaction to be marked for + * rollback so it is up to the calling code to trigger a rollback if needed. + * This allows the calling code to handle the exception and continue the + * transaction. + */ +public interface IRepositoryService { + + /** String used to define service in Spring context */ + public static final String REPOSITORY_SERVICE_ID = "repositoryService"; + /** Context files, using the JNDI datasource. Use for JBOSS */ + public static final String[] REPOSITORY_CONTEXT_PATH = new String[] { + "/org/lamsfoundation/lams/contentrepository/applicationContext.xml", + "/org/lamsfoundation/lams/applicationContext.xml", "/org/lamsfoundation/lams/toolApplicationContext.xml" }; + /** Context files, using a local datasource. Use for junit testing */ + public static final String[] REPOSITORY_LOCAL_CONTEXT_PATH = new String[] { + "/org/lamsfoundation/lams/contentrepository/applicationContext.xml", + "/org/lamsfoundation/lams/toolApplicationContext.xml" }; + + /** + * Login, creating a new ticket for the given credentials and specified + * workspace. If login fails, a LoginException is thrown and + * no valid ticket is generated. The credentials object in the ticket + * does not contain the password. + * + * It does not clear the password in the input credentials object. + * + * @param credentials + * The credentials of the user + * @param workspaceName + * the name of a workspace. + * @return a valid {@link ITicket} for the user to access the repository. + * @throws LoginException + * Login authentication fails. + * @throws AccessDeniedException + * User is not allowed to access this workspace. + * @throws WorkspaceNotFoundException + * Workspace name doesn't exist. + */ + public ITicket login(ICredentials credentials, String workspaceName) + throws LoginException, AccessDeniedException, WorkspaceNotFoundException; + + /** + * Create a new workspace, with the tool identified in the creditials + * as the owner. + * It does not clear the password in the credentials + * + * @param credentials + * this user/password must already exist in the repository. Password will be checked. + * @param workspaceName + * @throws LoginException + * if credentials are not authorised to add/access the new workspace. + * @throws ItemExistsException + * if the workspace already exists. + * @throws RepositoryCheckedException + * if parameters are missing. + */ + public CrWorkspace addWorkspace(ICredentials credentials, String workspaceName) + throws LoginException, AccessDeniedException, ItemExistsException, RepositoryCheckedException; + + /** + * Create a new repository "user" - usually a tool. + * + * The password must be at least 6 chars. + * + * This method will not wipe out the password in the newCredential object. + * + * At this stage it is publically accessable - may need to move + * it to a private management tool if considered to insecure. + * + * @param newCredential + * this user/password will be added to the repository + * @throws RepositoryCheckedException + * if parameters are missing. + * @throws ItemExistsException + * if the credential already exists. + */ + public void createCredentials(ICredentials newCredential) + throws AccessDeniedException, RepositoryCheckedException, ItemExistsException; + + /** + * Update a credential. Name cannot change, so really only the password changes + * + * The password must be at least 6 chars. + * + * @param oldCredential + * the current user/password + * @param newCredential + * the new user/password + * @throws LoginException + * if the oldCredential fails login test (e.g. wrong password) + * @throws RepositoryCheckedException + * if one of the credentials objects are missing + */ + public void updateCredentials(ICredentials oldCredential, ICredentials newCredential) + throws AccessDeniedException, RepositoryCheckedException; + + /** + * Add a new file to the repository. This will create + * a completely new entry (node) in the repository, starting + * with version 1. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param istream + * new file, as an input stream - mandatory + * @param mimeType + * mime type of file - optional + * @param versionDescription + * human readable comment about the version - optional + * @return nodeKey (uuid and version) + * @throws AccessDeniedException + * if ticket doesn't allow this action + * @throws FileException + * if unable to save node due to file error + * @throws InvalidParameterException + * if a required parameter is missing + * @throws RepositoryRuntimeException + * if any internal errors have occured + */ + public abstract NodeKey addFileItem(ITicket ticket, InputStream istream, String filename, String mimeType, + String versionDescription) throws FileException, AccessDeniedException, InvalidParameterException; + + /** + * Add a new package of files to the repository. If startFile + * is not supplied, then it is assumed to be index.html. + * + * The directory separator character in the paths of the files in the package + * will be converted to "/" so that a web style path can be used to + * access the file. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param dirPath + * directory path containing files - mandatory + * @param startFile + * relative path of initial file - optional + * @param versionDescription + * human readable comment about the version - optional + * @return nodeKey (uuid and version) + * @throws AccessDeniedException + * if ticket doesn't allow this action + * @throws FileException + * if unable to save node due to file error + * @throws InvalidParameterException + * if a required parameter is missing + * @throws RepositoryRuntimeException + * if any internal errors have occured + */ + public abstract NodeKey addPackageItem(ITicket ticket, String dirPath, String startFile, String versionDescription) + throws AccessDeniedException, InvalidParameterException, FileException; + + /** + * Update an existing file in the repository. This will create + * a new version of this file. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param uuid + * unique id of the file - mandatory + * @param istream + * new file, as an input stream - mandatory + * @param versionDescription + * human readable comment about the version - optional + * @param mimeType + * mime type of file - optional + * @throws AccessDeniedException + * if ticket doesn't allow this action + * @throws ItemNotFoundException + * if node with uuid cannot be found + * @throws FileException + * if unable to save node due to file error + * @throws InvalidParameterException + * if a required parameter is missing + * @throws RepositoryRuntimeException + * if any internal errors have occured + */ + public NodeKey updateFileItem(ITicket ticket, Long uuid, String filename, InputStream istream, String mimeType, + String versionDescription) + throws AccessDeniedException, ItemNotFoundException, FileException, InvalidParameterException; + + /** + * Add a new package of files to the repository. If startFile + * is not supplied, then it is assumed to be index.html. + * + * The directory separator character in the paths of the files in the package + * will be converted to "/" so that a web style path can be used to + * access the file. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param uuid + * unique id of the package - mandatory + * @param dirPath + * directory path containing files - mandatory + * @param startFile + * relative path of initial file - optional + * @param versionDescription + * human readable comment about the version - optional + * @return nodeKey (uuid and version) + * @throws AccessDeniedException + * if ticket doesn't allow this action + * @throws ItemNotFoundException + * if node with uuid cannot be found + * @throws FileException + * if unable to save node due to file error + * @throws InvalidParameterException + * if a required parameter is missing + * @throws RepositoryRuntimeException + * if any internal errors have occured + */ + public abstract NodeKey updatePackageItem(ITicket ticket, Long uuid, String dirPath, String startFile, + String versionDescription) + throws AccessDeniedException, ItemNotFoundException, FileException, InvalidParameterException; + + /** + * Sets the property to a value, based on the specified type. Removes the property if the value is null. + * + * @param ticket + * Mandatory + * @param uuid + * Mandatory + * @param versionId + * Mandatory + * @param name + * The name of a property of this node + * @param value + * The value to be assigned + * @param type + * The type of the property. See org.lamsfoundation.lams.contentrepository.PropertyType + * for values. + * @throws ValueFormatException + * if the type or format of a value + * is incompatible with the type of the specified property or if + * value is incompatible with (i.e. can not be converted to) type. + */ + public void setProperty(ITicket ticket, Long uuid, Long versionId, String name, Object value, int type) + throws AccessDeniedException, ItemNotFoundException, ValidationException; + + /** + * Copy node, copying the specified/latest version of the existing node + * to version 1 of the new node. + *
+ * Copies a node (identified by uuid/version). The file(s) attached to the + * supplied version are duplicated and become version 1 of the new node. Therefore + * any "history" of the original node is lost. If the version is not supplied, + * then it uses the latest version of the node as the basis for the new node. + *
+ * This method works for both file nodes and package nodes. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param uuid + * id of the file/package - mandatory + * @param version + * desired version - if null gets latest version + * @return nodeKey (uuid and version) + * @throws AccessDeniedException + * if the ticket is invalid + * @throws ItemNotFoundException + * if the node cannot be found + */ + public NodeKey copyNodeVersion(ITicket ticket, Long uuid, Long versionId) + throws AccessDeniedException, ItemNotFoundException; + + /** + * Get an item from the repository based on the UUID. This + * may be either a file or package node. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param uuid + * id of the file/package - mandatory + * @param version + * desired version - if null gets latest version + * @return node. + */ + public abstract IVersionedNode getFileItem(ITicket ticket, Long uuid, Long version) + throws AccessDeniedException, ItemNotFoundException, FileException; + + /** + * Get an item from the repository based on the UUID and relative + * path. Only used to get the content from a package. The + * UUID is the id of the package, and relPath is the relative + * path within the package. + * + * If the item is a package and relPath is null, return the package node. + * + * The relPath must be specified in web format ie use a separator + * of "/" not "\". + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param uuid + * id of the package - mandatory + * @param versionId + * desired version - if null gets latest version. This is the version + * of the package node, not the related file. + * @param relPath + * relative path within the package - if null, + * returns start file. + * @throws AccessDeniedException + * if ticket doesn't allow this action + * @throws ItemNotFoundException + * if node with uuid cannot be found + * @throws FileException + * if unable to save node due to file error + * @throws RepositoryRuntimeException + * if any internal errors have occured + * @return node. + */ + public abstract IVersionedNode getFileItem(ITicket ticket, Long uuid, Long versionId, String relPath) + throws AccessDeniedException, ItemNotFoundException, FileException; + + /** + * Return a list of all the nodes for a package. The first in the list + * is the package node. The others are in arbitrary order. + * + * @param ticket + * @param uuid + * uuid of the package node + * @param version + * version of the package node + * @return list of all nodes for package. + * @throws AccessDeniedException + * @throws ItemNotFoundException + * @throws FileException + */ + public List getPackageNodes(ITicket ticket, Long uuid, Long version) + throws AccessDeniedException, ItemNotFoundException, FileException; + + /** + * Get the history for a node. Quite intensive operation the + * first time it is run on a node as it has to build all the + * data structures. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @return SortedSet of IVersionDetail objects, ordered by version + */ + public SortedSet getVersionHistory(ITicket ticket, Long uuid) throws ItemNotFoundException, AccessDeniedException; + + /** + * Delete the current version of a node, returning a list of the files + * that could not be deleted properly. If it is a package node, the child + * nodes will be deleted. + * + * You cannot delete the child of a package node - you have to delete the + * whole package. + * + * If after deleting the version, we find that there a no other versions + * for a node, then delete the node. + * + * A file missing from the disk is ignored, allowing nodes with lost files + * to be deleted. + * + * @throws AccessDeniedException + * if ticket doesn't allow this action + * @throws ItemNotFoundException + * if node with uuid cannot be found + * @throws InvalidParameterException + * if a required parameter is missing + * @throws RepositoryRuntimeException + * if any internal errors have occured + * @return the list of file(paths) that could not be deleted. The db entries + * will have been deleted but these files could not be deleted. + */ + public String[] deleteVersion(ITicket ticket, Long uuid, Long version) + throws AccessDeniedException, InvalidParameterException, ItemNotFoundException; + + /** + * Delete a node and all its versions, returning a list of the files + * that could not be deleted properly. If it is a package node, the child + * nodes will be deleted. + * + * A file missing from the disk is ignored, allowing nodes with lost files + * to be deleted. + * + * @throws AccessDeniedException + * if ticket doesn't allow this action + * @throws ItemNotFoundException + * if node with uuid cannot be found + * @throws InvalidParameterException + * if a required parameter is missing + * @throws RepositoryRuntimeException + * if any internal errors have occured + * @return the list of file(paths) that could not be deleted. The db entries + * will have been deleted but these files could not be deleted. + */ + public String[] deleteNode(ITicket ticket, Long uuid) + throws AccessDeniedException, InvalidParameterException, ItemNotFoundException; + + /** + * Finish using this ticket. No more updates may be used with this ticket + * after logout(). Allows any resources to be freed. + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + */ + public void logout(ITicket ticket) throws AccessDeniedException; + + /** + * Get a complete list of all nodes in the workspace and their + * version histories. + *
+ * Warning: Once a workspace gets a lot of nodes, this will be + * a very very expensive call!!!!! + *
+ * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @return SortedMap key Long uuid, value IVersionDetail version history + */ + public SortedMap getNodeList(ITicket ticket) throws AccessDeniedException; + + /** + * Save current version of a node to local file by given file name. If thetoFileName is
+ * null, file name use original file name instead and file save path will be system temporary directory.
+ * + * + * @param ticket + * ticket issued on login. Identifies tool and workspace - mandatory + * @param uuid + * id of the file/package - mandatory + * @param version + * desired version - if null gets latest version + * + * @param toFileName + * the local file name with directory information. + */ + public void saveFile(ITicket ticket, Long uuid, Long versionId, String toFileName) + throws RepositoryCheckedException, AccessDeniedException, ItemNotFoundException, IOException; + + public boolean workspaceExists(ICredentials credentials, Long workspaceId); + + public boolean workspaceExists(ICredentials credentials, String workspaceName); +} \ No newline at end of file Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/ITicket.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/NodeKey.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/client/IToolContentHandler.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/client/ToolContentHandler.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/exception/FileException.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/exception/InvalidParameterException.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/exception/ItemNotFoundException.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/exception/RepositoryCheckedException.java'. Fisheye: No comparison available. Pass `N' to diff? Fisheye: Tag 46fe95e04d6fbe8fec9e41f054a711e23c1e064c refers to a dead (removed) revision in file `lams_contentrepository/src/java/org/lamsfoundation/lams/contentrepository/service/IRepositoryService.java'. Fisheye: No comparison available. Pass `N' to diff?