no-jira: fix documentation of REST API, fix wrong path of the LogWebService,...

no-jira: fix documentation of REST API, fix wrong path of the LogWebService, backport RegistrationWebService to OpenOLAT with its unit tests

src/main/java/org/olat/registration/restapi/RegistrationWebService.java

+/**
+ * OLAT - Online Learning and Training<br>
+ * http://www.olat.org
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License"); <br>
+ * you may not use this file except in compliance with the License.<br>
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing,<br>
+ * software distributed under the License is distributed on an "AS IS" BASIS, <br>
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. <br>
+ * See the License for the specific language governing permissions and <br>
+ * limitations under the License.
+ * <p>
+ * Copyright (c) frentix GmbH<br>
+ * http://www.frentix.com<br>
+ * <p>
+ */
+package org.olat.registration.restapi;
+
+import static org.olat.restapi.security.RestSecurityHelper.getLocale;
+
+import java.net.URI;
+import java.text.DateFormat;
+import java.util.Date;
+import java.util.Locale;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.ws.rs.FormParam;
+import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.ResponseBuilder;
+import javax.ws.rs.core.Response.Status;
+import javax.ws.rs.core.UriBuilder;
+
+import org.olat.core.CoreSpringFactory;
+import org.olat.core.gui.translator.Translator;
+import org.olat.core.helpers.Settings;
+import org.olat.core.logging.OLog;
+import org.olat.core.logging.Tracing;
+import org.olat.core.util.Util;
+import org.olat.core.util.i18n.I18nManager;
+import org.olat.core.util.mail.MailerResult;
+import org.olat.core.util.mail.manager.MailManager;
+import org.olat.registration.RegistrationController;
+import org.olat.registration.RegistrationManager;
+import org.olat.registration.RegistrationModule;
+import org.olat.registration.TemporaryKey;
+import org.olat.user.UserManager;
+
+
+/**
+ * 
+ * Description:<br>
+ * Web service to trigger the registration process
+ * 
+ * <P>
+ * Initial Date:  14 juil. 2011 <br>
+ *
+ * @author srosse, stephane.rosse@frentix.com, http://www.frentix.com
+ */
+@Path("registration")
+public class RegistrationWebService {
+	
+	private OLog log = Tracing.createLoggerFor(RegistrationWebService.class);
+
+	private static final String SEPARATOR = "____________________________________________________________________\n";
+	
+	/**
+	 * Register with the specified email
+   * @response.representation.200.doc Registration successful
+   * @response.representation.304.doc Already registered, HTTP-Header location set to redirect
+   * @param email The email address
+   * @param request The HTTP Request
+	 * @return
+	 */
+	@POST
+	public Response registerPost(@FormParam("email") String email, @Context HttpServletRequest request) {
+		return register(email, request);
+	}
+	
+	/**
+	 * Register with the specified email
+   * @response.representation.200.doc Registration successful
+   * @response.representation.304.doc Already registered, HTTP-Header location set to redirect
+   * @param email The email address
+   * @param request The HTTP Request
+	 * @return
+	 */
+	@PUT
+	public Response register(@QueryParam("email") String email, @Context HttpServletRequest request) {
+		if (!CoreSpringFactory.getImpl(RegistrationModule.class).isSelfRegistrationEnabled()) {
+			return Response.serverError().status(Status.NOT_FOUND).build();
+		}
+		
+		ResponseBuilder response;
+		Locale locale = getLocale(request);
+		Translator translator = getTranslator(locale);
+		
+		MailManager mailM = MailManager.getInstance();
+		UserManager userManager = UserManager.getInstance();
+		RegistrationManager rm = RegistrationManager.getInstance();
+		
+		boolean foundUser = userManager.userExist(email);
+		// get remote address
+
+		String serverpath = Settings.getServerContextPathURI();
+		if (foundUser) {
+			//redirect
+			URI redirectUri = UriBuilder.fromUri(Settings.getServerContextPathURI()).build();
+			response = Response.ok().status(Status.NOT_MODIFIED).location(redirectUri);
+		} else {
+			String ip = request.getRemoteAddr();
+			TemporaryKey tk = rm.loadTemporaryKeyByEmail(email);
+			if (tk == null) {
+				tk = rm.createTemporaryKeyByEmail(email, ip, RegistrationManager.REGISTRATION);
+			}
+			String today = DateFormat.getDateInstance(DateFormat.LONG, locale).format(new Date());
+			String body = translator.translate("reg.body",
+					new String[] { serverpath, tk.getRegistrationKey(), I18nManager.getInstance().getLocaleKey(locale) })
+					+ SEPARATOR
+					+ translator.translate("reg.wherefrom", new String [] { serverpath, today, ip });
+			try {
+				MailerResult result = mailM.sendExternMessage(null, null, null, email, null, null, null, translator.translate("reg.subject"), body, null, null);
+				if (MailerResult.OK == result.getReturnCode()) {
+					response = Response.ok();
+				} else {
+					response = Response.serverError().status(Status.INTERNAL_SERVER_ERROR);
+				}
+			} catch (Exception e) {
+				response = Response.serverError().status(Status.INTERNAL_SERVER_ERROR);
+				log.error("", e);
+			}
+		}
+		
+		return response.build();
+	}
+	
+	private Translator getTranslator(Locale locale) {
+		return Util.createPackageTranslator(RegistrationController.class, locale);
+	}
+
+}

src/main/java/org/olat/restapi/_spring/restApiContext.xml

@@ -29,7 +29,7 @@
 				<value>org.olat.user.restapi.ContactsWebService</value>
 				<value>org.olat.user.restapi.UserAuthenticationWebService</value>
 				<value>org.olat.restapi.group.LearningGroupWebService</value>
-				<value>org.olat.restapi.user.UserFoldersWebService</value>
+				<value>org.olat.user.restapi.UserFoldersWebService</value>
 				<value>org.olat.restapi.repository.RepositoryEntriesResource</value>
 				<value>org.olat.restapi.repository.course.CourseWebService</value>
 				<value>org.olat.restapi.repository.course.CoursesWebService</value>
@@ -46,8 +46,9 @@
 				<value>org.olat.modules.fo.restapi.MyForumsWebService</value>
 				<value>org.olat.catalog.restapi.CatalogWebService</value>
 				<value>org.olat.notifications.restapi.NotificationsWebService</value>
+				<value>org.olat.registration.restapi.RegistrationWebService</value>
 				<value>org.olat.commons.calendar.restapi.CalendarWebService</value>
-				<value>org.olat.restapi.log.LogWebService</value>
+				<value>org.olat.restapi.system.LogWebService</value>
 				<value>org.olat.restapi.system.SystemWebService</value>
 			</list>
 		</property>

src/main/java/org/olat/user/restapi/Examples.java

@@ -33,6 +33,8 @@ public class Examples {
 	
 	public static final UserVO SAMPLE_USERVO = new UserVO();
 	public static final UserVOes SAMPLE_USERVOes = new UserVOes();
+
+	public static final RolesVO SAMPLE_ROLESVO = new RolesVO();
   
   static {
   	SAMPLE_USERVO.setKey(345l);
@@ -44,5 +46,7 @@ public class Examples {
   	SAMPLE_USERVO.putProperty("telPrivate", "238456782");
   	SAMPLE_USERVO.putProperty("telMobile", "238456782");
   	SAMPLE_USERVOes.setUsers(new UserVO[]{SAMPLE_USERVO});
+
+  	SAMPLE_ROLESVO.setAuthor(true);
   }
 }

src/main/java/org/olat/restapi/user/UserFoldersWebService.java → src/main/java/org/olat/user/restapi/UserFoldersWebService.java

@@ -17,7 +17,7 @@
  * 2011 by frentix GmbH, http://www.frentix.com
  * <p>
 **/
-package org.olat.restapi.user;
+package org.olat.user.restapi;
 
 import static org.olat.restapi.security.RestSecurityHelper.getIdentity;
 import static org.olat.restapi.security.RestSecurityHelper.getRoles;
@@ -39,7 +39,6 @@ import javax.ws.rs.Produces;
 import javax.ws.rs.WebApplicationException;
 import javax.ws.rs.core.Context;
 import javax.ws.rs.core.MediaType;
-import javax.ws.rs.core.Request;
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.Response.Status;
 
@@ -168,13 +167,12 @@ public class UserFoldersWebService {
 	 * @response.representation.401.doc The roles of the authenticated user are not sufficient
 	 * @param identityKey The key of the user (IdentityImpl)
 	 * @param httpRequest The HTTP request
-	 * @param request The REST request
 	 * @return The folders
 	 */
 	@GET
 	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 	public Response getFolders(@PathParam("identityKey") Long identityKey,
-			@Context HttpServletRequest httpRequest, @Context Request request) {
+			@Context HttpServletRequest httpRequest) {
 		
 		Roles roles;
 		Identity retrievedUser = getIdentity(httpRequest);

src/main/java/org/olat/user/restapi/UserWebService.java

@@ -311,7 +311,6 @@ public class UserWebService {
 	 * @param withPortrait If true return the portrait as Base64 (default false)
 	 * @param uriInfo The URI infos
 	 * @param httpRequest The HTTP request
-	 * @param request The REST request
 	 * @return an xml or json representation of a the user being search. The xml
 	 *         correspond to a <code>UserVO</code>. <code>UserVO</code> is a
 	 *         simplified representation of the <code>User</code> and <code>Identity</code>
@@ -320,7 +319,7 @@ public class UserWebService {
 	@Path("{identityKey}")
 	@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
 	public Response findById(@PathParam("identityKey") Long identityKey, @QueryParam("withPortrait") @DefaultValue("false") Boolean withPortrait,
-			@Context UriInfo uriInfo, @Context HttpServletRequest httpRequest, @Context Request request) {
+			@Context UriInfo uriInfo, @Context HttpServletRequest httpRequest) {
 		try {
 			Identity identity = BaseSecurityManager.getInstance().loadIdentityByKey(identityKey, false);
 			if(identity == null) {

src/test/java/org/olat/restapi/RegistrationTest.java

+/**
+ * OLAT - Online Learning and Training<br>
+ * http://www.olat.org
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License"); <br>
+ * you may not use this file except in compliance with the License.<br>
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing,<br>
+ * software distributed under the License is distributed on an "AS IS" BASIS, <br>
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. <br>
+ * See the License for the specific language governing permissions and <br>
+ * limitations under the License.
+ * <p>
+ * Copyright (c) frentix GmbH<br>
+ * http://www.frentix.com<br>
+ * <p>
+ */
+package org.olat.restapi;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.util.UUID;
+
+import org.apache.http.Header;
+import org.apache.http.HttpResponse;
+import org.apache.http.client.methods.HttpPut;
+import org.apache.http.util.EntityUtils;
+import org.junit.Before;
+import org.junit.Test;
+import org.olat.core.id.Identity;
+import org.olat.core.id.UserConstants;
+import org.olat.restapi.RestConnection;
+import org.olat.test.JunitTestHelper;
+import org.olat.test.OlatJerseyTestCase;
+
+/**
+ * 
+ * Description:<br>
+ * 
+ * <P>
+ * Initial Date:  14 juil. 2011 <br>
+ *
+ * @author srosse, stephane.rosse@frentix.com, http://www.frentix.com
+ */
+public class RegistrationTest extends OlatJerseyTestCase {
+	
+	private static Identity owner1;
+	
+	@Before
+	@Override
+	public void setUp() throws Exception {
+		super.setUp();
+		//create a course with learn group
+		
+		owner1 = JunitTestHelper.createAndPersistIdentityAsUser("rest-one");
+	}
+
+	@Test
+	public void testRegistration() throws IOException, URISyntaxException {
+		RestConnection conn = new RestConnection();
+
+		String randomEmail = UUID.randomUUID().toString().replace("-", "") + "@frentix.com";
+		URI uri = conn.getContextURI().path("registration").queryParam("email", randomEmail).build();
+		HttpPut put = conn.createPut(uri, "*/*", "de", true);
+		
+		HttpResponse response = conn.execute(put);
+		assertEquals(200, response.getStatusLine().getStatusCode());
+		EntityUtils.consume(response.getEntity());
+		
+		conn.shutdown();
+	}
+	
+	@Test
+	public void testRedirectRegistration() throws IOException, URISyntaxException {
+		RestConnection conn = new RestConnection();
+
+		URI uri = conn.getContextURI().path("registration")
+				.queryParam("email", owner1.getUser().getProperty(UserConstants.EMAIL, null)).build();
+		HttpPut put = conn.createPut(uri, "*/*", "de", true);
+
+		HttpResponse response = conn.execute(put);
+		assertEquals(304, response.getStatusLine().getStatusCode());
+		Header locationHeader = response.getFirstHeader("location");
+		assertNotNull(locationHeader);
+		assertNotNull(locationHeader.getValue());
+		
+		conn.shutdown();
+	}
+}

src/test/java/org/olat/test/AllTestsJunit4.java

@@ -157,6 +157,7 @@ import org.junit.runners.Suite;
 	org.olat.restapi.UserMgmtTest.class,
 	org.olat.restapi.ContactsTest.class,
 	org.olat.restapi.SystemTest.class,
+	org.olat.restapi.RegistrationTest.class,
 	de.bps.olat.portal.institution.InstitutionPortletTest.class,
 	org.olat.group.manager.BusinessGroupImportExportXStreamTest.class,
 	org.olat.group.test.BusinessGroupImportExportTest.class,