1 /****************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 ****************************************************************/
19
20 package org.apache.james.mailrepository.javamail;
21
22 import javax.mail.Folder;
23 import javax.mail.MessagingException;
24
25 /**
26 * offers access to an underlaying Folder and manages open/close operations.<br>
27 * The FolderGateKeeper can be handed over to different threads.
28 * <br>
29 * Clients have to call use() one time before and free() one time after they are
30 * operating on the folder. When use() has been called free() has to be called
31 * afterwards in any circumstance usally in a finally block.<br>
32 *
33 * <pre>
34 * try {
35 * use();
36 * getFolder().doSomething();
37 * getFolder().doSomething();
38 * } finally {
39 * free();
40 * }
41 * </pre>
42 *
43 * It is not allowed to open/close Folder from outside.
44 */
45
46 public interface FolderGateKeeper {
47
48 /**
49 * increments count of users
50 */
51 public void use();
52
53 /**
54 * decrements count of users and closes folder if 0 and folder is open.
55 *
56 * @throws MessagingException
57 * if something went wrong closing the Folder
58 * @throws IllegalStateException
59 * if there are already 0 users
60 * @throws IllegalStateException
61 * if the state of the folder differs from the last known
62 */
63 public void free() throws MessagingException;
64
65 /**
66 * Gets the Folder and opens it, if necessary
67 *
68 * @return an open Folder
69 * @throws MessagingException
70 * if something went wron opening the Folder
71 * @throws IllegalStateException
72 * if the state of the folder differs from the last known
73 * @throws IllegalStateException
74 * if there are only 0 users
75 */
76 public FolderInterface getOpenFolder() throws MessagingException;
77
78 /**
79 * used to test whether everyone has freed it
80 *
81 * @return number of users
82 */
83 public int getUseCount();
84
85 /**
86 * Gets the Folder and don't care whether it is open or closed.
87 *
88 * @return a open or closed Folder
89 * @throws IllegalStateException
90 * if the state of the folder differs from the last known
91 * @throws IllegalStateException
92 * if there are only 0 users
93 */
94 public FolderInterface getFolder();
95
96 /**
97 * @see javax.mail.Folder#getFullName()
98 */
99 public String getFullName() throws MessagingException;
100
101 /**
102 * @see javax.mail.Folder
103 */
104 public void create(int holds_folders) throws MessagingException;
105
106 /**
107 * @see javax.mail.Folder#exists()
108 */
109 public boolean exists() throws MessagingException;
110
111 /**
112 * @see javax.mail.Folder#renameTo(Folder)
113 */
114 void renameTo(Folder folder) throws MessagingException;
115
116 /**
117 * @see javax.mail.Folder#renameTo(Folder)
118 */
119 public void renameTo(String newName) throws MessagingException;;
120
121 }