View Javadoc

1   /*
2    * Copyright 2000-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.portals.graffito.jcr.persistence.collectionconverter;
17  
18  import javax.jcr.Node;
19  import javax.jcr.Session;
20  
21  import org.apache.portals.graffito.jcr.exception.PersistenceException;
22  import org.apache.portals.graffito.jcr.mapper.model.CollectionDescriptor;
23  
24  /***
25   * Convert any kind of {@link ManageableCollection} into severals JCR nodes.
26   * 
27   * @author <a href="mailto:christophe.lombart@sword-technologies.com">Lombart Christophe </a>
28   * 
29   */
30  public interface CollectionConverter
31  {
32  
33  	/***
34  	 * Insert/convert collection elements into some JCR nodes
35  	 * @param session The JCR session 
36  	 * @param parentNode the node which will contains the collection element
37  	 * @param collectionDescriptor The collection descriptor
38  	 * @param collection the collection to insert
39  	 * 
40  	 * @throws PersistenceException when it is not possible to insert the collection
41  	 * 
42  	 */
43  	public void insertCollection(Session session, Node parentNode, 
44  			                     CollectionDescriptor collectionDescriptor, ManageableCollection collection) throws PersistenceException;
45  
46  	/***
47  	 * Update collection elements already present in the JCR repository
48  	 * @param session The JCR session 
49  	 * @param parentNode the node which will contains the collection element
50  	 * @param collectionDescriptor The collection descriptor
51  	 * @param collection the collection to update
52  	 * 
53  	 * @throws PersistenceException when it is not possible to update the collection
54  	 */
55  	public void updateCollection(Session session, Node parentNode, 
56  			                     CollectionDescriptor collectionDescriptor, ManageableCollection collection) throws PersistenceException;
57  
58  	/***
59  	 * Get a {@link ManageableCollection} from the JCR repository 
60  	 * @param session The JCR session 
61  	 * @param parentNode the node which contains the collection element
62  	 * @param collectionDescriptor The collection descriptor
63  	 * @param collectionFieldClass The collection class to used (ArrayList, Vector, ..) 
64  	 * @return The collection populates with all elements found in the JCR repository
65  	 * 
66  	 * @throws PersistenceException when it is not possible to retrieve the collection 
67  	 */
68  	public ManageableCollection getCollection(Session session, Node parentNode, 
69  			                                  CollectionDescriptor collectionDescriptor, Class collectionFieldClass) throws PersistenceException;
70  
71  	
72  	/***
73  	 * Check if the collection is null. This method is mainly used in the Proxy manager to return a null value or a proxy object
74  	 * Without proxy proxy, this method is never called. 
75  	 * 
76  	 * @param session The JCR session 
77  	 * @param parentNode the node which contains the collection element
78  	 * @param collectionDescriptor The collection descriptor
79  	 * @param collectionFieldClass The collection class to used (ArrayList, Vector, ..) 
80  	 * @return true if the collection contains elements.
81  	 * 
82  	 * 
83  	 * @throws PersistenceException when it is not possible to retrieve the collection 
84  	 */	
85  	public boolean isNull(Session session, Node parentNode, 
86                                        CollectionDescriptor collectionDescriptor, Class collectionFieldClass) throws PersistenceException;
87  }