1 /**
2 * Copyright 2005-2008 the original author or authors.
3 *
4 * Licensed under the Gnu General Pubic License, Version 2.0 (the
5 * "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/gpl-license.php
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13 * See the Gnu General Public License for more details.
14 */
15 package org.figure8.join.services.remoting.xmlrpc;
16
17 import org.figure8.join.core.DuplicateEntityException;
18 import org.figure8.join.core.InvalidParameterException;
19 import org.figure8.join.services.security.InvalidLoginException;
20 import org.figure8.join.services.remoting.InvalidSessionException;
21
22 import java.rmi.RemoteException;
23 import java.util.List;
24 /**
25 * This is an interface for a service handler dedicated to Xml-Rpc protocol.
26 * For this reason, operations signature are simplified in order to be easily bounded
27 * to their Xml-Rpc serialization representation.
28 * @author <a href="mailto:laurent.broudoux@free.fr">Laurent Broudoux</a>
29 * @version $Revision: 1.3 $
30 */
31 public interface XmlRpcHandler{
32
33
34
35 /**
36 * Authenticates a remote user onto Join application. In case of successfull
37 * authentication, this method returns a token that should be used later as
38 * a parameter for calling services required authorization.
39 * @param username Login of user for authentication
40 * @param password Password of corresponding user
41 * @return An authentication token to reuse later during service call
42 * @throws InvalidLoginException if user cannot be logged
43 * @throws RemoteException if an exception occurs during the remote conversation
44 */
45 public abstract String login(String username, String password)
46 throws InvalidLoginException, RemoteException;
47
48 /**
49 * Logs out from Join application the user corresponding to the supplied token.
50 * @param token An authentication token obtained with <code>login()</code> method.
51 * @throws RemoteException if an exception occurs during the remote conversation
52 * @return Wether this operation is successfull
53 */
54 public abstract boolean logout(String token) throws RemoteException;
55
56 /**
57 * Retrieve all the releases managed within the project.
58 * @param token Authentication token provided earlier by login() method
59 * @return An array representing RemoteRelease objects
60 * @throws InvalidSessionException if user has no valid session on server-side
61 * @throws RemoteException if an exception occurs during the remote conversation
62 */
63 public abstract List getReleases(String token) throws InvalidSessionException, RemoteException;
64
65 /**
66 * Retrieve all the deliverable categories (or types) managed within the project.
67 * @param token Authentication token provided earlier by login() method
68 * @return An array representing RemoteDeliverableType objects
69 * @throws InvalidSessionException if user has no valid session on server-side
70 * @throws RemoteException if an exception occurs during the remote conversation
71 */
72 public abstract List getDeliverableTypes(String token) throws InvalidSessionException, RemoteException;
73
74 /**
75 * Get the deliverable categories where authenticated user can supply deliverables for.
76 * @param token Authentication token provided earlier by login() method
77 * @return An array representing RemoteDeliverableType objects for deliverables supplying
78 * @throws InvalidSessionException if user has no valid session on server-side
79 * @throws RemoteException if an exception occurs during the remote conversation
80 */
81 public abstract List getDeliverableTypesForDelivery(String token) throws InvalidSessionException, RemoteException;
82
83 /**
84 * Supply a new deliverable using the remote wrapper. This wrapper must contains
85 * release and type informations. This delivery may include a File object as deliverable
86 * content if deliverables from this type are not retrieved using direct VCS or SCM connection.
87 * @param token Authentication token provided earlier by login() method
88 * @param releaseName The unique name of Release to supply a deliverable for
89 * @param typeKey The unique key of deliverable type this delivery will be bound to
90 * @param versionInfo The version info (or VCS tag info) for this delivery
91 * @param comments The comments on deliverable creation
92 * @param content The deliverable content if not VCS deliverable
93 * @throws InvalidParameterException if deliverable is already registered or parameter is missing
94 * @throws DuplicateEntityException if another deliverable with same key already exists
95 * @throws InvalidSessionException if user has no valid session on server-side
96 * @throws RemoteException if an exception occurs during the remote conversation
97 * @return Wether this operation is successfull
98 */
99 public abstract boolean supplyDeliverable(String token, String releaseName, String typeKey,
100 String versionInfo, String comments, byte[] content)
101 throws InvalidParameterException, DuplicateEntityException, InvalidSessionException, RemoteException;
102
103 /**
104 * Bind a component to a given assembly.
105 * @param token Authentication token provided earlier by login() method
106 * @param typeKey The unique key of component type this component will be bound to
107 * @param versionInfo The version info for this component
108 * @param size The size in bytes of this component
109 * @param assemblyKey The key of assembly to bind component to
110 * @throws InvalidParameterException if parameter is missing
111 * @throws InvalidSessionException if user has no valid session on server-side
112 * @throws RemoteException if an exception occurs during the remote conversation
113 * @return Wether this operation is successfull
114 */
115 public abstract boolean bindComponent(String token, String typeKey, String versionInfo,
116 long size, String assemblyKey)
117 throws InvalidParameterException, InvalidSessionException, RemoteException;
118
119 /**
120 * Set the specified status to a specified <code>Build</code>.
121 * @param token Authentication token provided earlier by login() method
122 * @param statusKey Unique key idenitifer of the status to set to build
123 * @param buildKey The unique key idenitifer of Build to update status
124 * @throws InvalidSessionException if user has no valid session on server-side
125 * @throws RemoteException if an exception occurs during the remote conversation
126 * @return Wether this operation is successfull
127 */
128 public abstract boolean setBuildStatus(String token, String statusKey, String buildKey)
129 throws InvalidSessionException, RemoteException;
130
131 /**
132 * Set the specified status to a specified <code>Assembly</code>.
133 * @param token Authentication token provided earlier by login() method
134 * @param statusKey Unique key idenitifer of the status to set to assembly
135 * @param assemblyKey The unique key idenitifer of Assembly to update status
136 * @throws InvalidSessionException if user has no valid session on server-side
137 * @throws RemoteException if an exception occurs during the remote conversation
138 * @return Wether this operation is successfull
139 */
140 public abstract boolean setAssemblyStatus(String token, String statusKey, String assemblyKey)
141 throws InvalidSessionException, RemoteException;
142
143 /**
144 * Set the specified status to a specified <code>Deployment</code>.
145 * @param token Authentication token provided earlier by login() method
146 * @param statusKey Unique key idenitifer of the status to set to deployment
147 * @param deploymentId The unique identifier of Deployment to update status for (must be a long)
148 * @throws InvalidSessionException if user has no valid session on server-side
149 * @throws NumberFormatException if deploymentId does not represent a long
150 * @throws RemoteException if an exception occurs during the remote conversation
151 * @return Wether this operation is successfull
152 */
153 public abstract boolean setDeploymentStatus(String token, String statusKey, String deploymentId)
154 throws InvalidSessionException, NumberFormatException, RemoteException;
155
156
157 /**
158 * Create a new resource version for a specified resource type. This operation
159 * reqires a valid authentication done first and the permissions corresponding
160 * to Joiner security role.
161 * @param token Authentication token provided earlier by login() method
162 * @param versionName The name of the resource version to create
163 * @param versionDescription The description of resource version to create
164 * @param resourceTypeKey The key of resource type this version applies to
165 * @throws InvalidParameterException if parameter is missing
166 * @throws DuplicateEntityException if another version with same name already exists
167 * @throws InvalidSessionException if user has no valid session on server-side
168 * @throws RemoteException if an exception occurs during the remote conversation
169 * @return Wether this operation is successfull
170 */
171 public abstract boolean createResourceVersion(String token, String versionName,
172 String versionDescription, String resourceTypeKey)
173 throws InvalidParameterException, DuplicateEntityException, InvalidSessionException, RemoteException;
174
175 /**
176 * Update an existing resource with an existing reosurce version. Resource and
177 * version are specified using their names that should be unique within Join system.
178 * This operations requires a valid authentication done first and the persmissions
179 * corresponding to Joiner security role.
180 * @param token Authentication token provided earlier by login() method
181 * @param resourceName The unique name of the resource to update
182 * @param versionName The unique name of the version to update resource with
183 * @throws InvalidParameterException if one of supplied parameters is invalid
184 * @throws InvalidSessionException if user has no valid session on server-side
185 * @throws RemoteException if an exception occurs during the remote conversation
186 * @return Wether this operation is successfull
187 */
188 public abstract boolean updateResource(String token, String resourceName, String versionName)
189 throws InvalidParameterException, InvalidSessionException, RemoteException;
190 }