Author: [email protected]
Date: Mon Feb 27 10:17:47 2012
New Revision: 2115
Log:
[AMDATUOPENSOCIAL-198] Improved the REST documentation, added missing State bean
Added:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/RestBean.java
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/State.java
Modified:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/UserPreferencesBean.java
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboard.java
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboards.java
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Gadget.java
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Specification.java
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/rest/DashboardRESTServiceImpl.java
Modified:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/UserPreferencesBean.java
==============================================================================
---
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/UserPreferencesBean.java
(original)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/UserPreferencesBean.java
Mon Feb 27 10:17:47 2012
@@ -73,7 +73,24 @@
m_values.add(value);
}
- public static UserPreferencesBean getExampleInstance() {
+
+
+ // ********************************************************** //
+ // ********** EXAMPLE beans for REST documentation ********** //
+ // ********************************************************** //
+ public static UserPreferencesBean getValueExample() {
+ UserPreferencesBean userPrefs = new UserPreferencesBean();
+ userPrefs.addValue(UserPreferenceValueBean.getExampleInstance());
+ return userPrefs;
+ }
+
+ public static UserPreferencesBean getDefinitionExample() {
+ UserPreferencesBean userPrefs = new UserPreferencesBean();
+
userPrefs.addDefinition(UserPreferenceDefinitionBean.getExampleInstance());
+ return userPrefs;
+ }
+
+ public static UserPreferencesBean getExample() {
UserPreferencesBean userPrefs = new UserPreferencesBean();
userPrefs.addValue(UserPreferenceValueBean.getExampleInstance());
userPrefs.addDefinition(UserPreferenceDefinitionBean.getExampleInstance());
Modified:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboard.java
==============================================================================
---
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboard.java
(original)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboard.java
Mon Feb 27 10:17:47 2012
@@ -20,6 +20,7 @@
import java.util.ArrayList;
import java.util.List;
+import javax.ws.rs.core.MediaType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlRootElement;
@@ -34,22 +35,31 @@
*/
@SuppressWarnings("restriction")
@XmlRootElement(name = "dashboard")
-public class Dashboard {
+public class Dashboard extends RestBean {
@SerializedName("id")
private String m_id;
-
+
@SerializedName("name")
private String m_name;
-
+
@SerializedName("layout")
private Layout m_layout;
-
+
@SerializedName("gadgets")
private List<Gadget> m_gadgets;
-
+
@SerializedName("links")
private List<AtomSyndicationLink> m_links;
+
+ public Dashboard() {
+ super();
+ }
+
+ private Dashboard(String mimeType) {
+ super(mimeType);
+ }
+
public String getId() {
return m_id;
}
@@ -57,7 +67,7 @@
public void setId(String id) {
m_id = id;
}
-
+
public String getName() {
return m_name;
}
@@ -83,14 +93,14 @@
public void setGadgets(List<Gadget> gadgets) {
m_gadgets = gadgets;
}
-
+
public void addGadget(Gadget gadget) {
if (m_gadgets == null) {
m_gadgets = new ArrayList<Gadget>();
}
m_gadgets.add(gadget);
}
-
+
@XmlElementWrapper(name = "links")
@XmlElement(name = "link")
public List<AtomSyndicationLink> getLinks() {
@@ -100,28 +110,46 @@
public void setLinks(final List<AtomSyndicationLink> links) {
m_links = links;
}
-
+
public void addLink(String href, String rel, String type) {
AtomSyndicationLink link = new AtomSyndicationLink();
link.setHref(href).setRel(rel).setType(type);
addLink(link);
}
-
+
public void addLink(AtomSyndicationLink link) {
if (m_links == null) {
m_links = new ArrayList<AtomSyndicationLink>();
}
m_links.add(link);
}
-
- public static Dashboard getExampleInstance() {
- Dashboard dashboard = new Dashboard();
+
+ public static Dashboard getExample(String mimeType, String httpMethod) {
+ Dashboard dashboard = new Dashboard(mimeType);
dashboard.setId("db1");
+ dashboard.setName("My dashboard");
dashboard.setLayout(Layout.getExampleInstance());
- dashboard.addGadget(Gadget.getExampleInstance());
- String baseUrl = "http://localhost/rest/dashboards/db1?alt=";;
- dashboard.addLink(new AtomSyndicationLink().setHref(baseUrl +
"json").setRel("alternate").setType("application/json"));
- dashboard.addLink(new AtomSyndicationLink().setHref(baseUrl +
"xml").setRel("self").setType("application/xml"));
+
+ // Append gadgets for GET and PUT
+ if ("GET".equals(httpMethod) || "PUT".equals(httpMethod)) {
+ Gadget gadget = Gadget.getExample(mimeType, httpMethod);
+ if ("PUT".equals(httpMethod)) {
+ gadget.setLinks(null);
+ gadget.getState().setSecuretoken(null);
+ gadget.getSpecification().setHeight(null);
+ gadget.getSpecification().setTitle(null);
+ gadget.getSpecification().setUserpreferences(null);
+ } else {
+ gadget.removeLinks("alternate");
+ }
+ dashboard.addGadget(gadget);
+ }
+
+ if (!"PUT".equals(httpMethod)) {
+ String baseUrl = "http://localhost/rest/dashboards/db1";;
+ dashboard.addLink(dashboard.createLink(baseUrl,
MediaType.APPLICATION_JSON));
+ dashboard.addLink(dashboard.createLink(baseUrl,
MediaType.APPLICATION_XML));
+ }
return dashboard;
}
}
Modified:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboards.java
==============================================================================
---
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboards.java
(original)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Dashboards.java
Mon Feb 27 10:17:47 2012
@@ -64,9 +64,14 @@
}
}
- public static Dashboards getExampleInstance() {
+ public static Dashboards getExample(String mimeType, String httpMethod) {
Dashboards dashboards = new Dashboards();
- dashboards.addDashboard(Dashboard.getExampleInstance());
+ Dashboard dashboard = Dashboard.getExample(mimeType, httpMethod);
+
+ // If we return a full dashboards example, we omit the gadgets (so
expand=false)
+ dashboard.setGadgets(null);
+
+ dashboards.addDashboard(dashboard);
return dashboards;
}
}
Modified:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Gadget.java
==============================================================================
---
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Gadget.java
(original)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Gadget.java
Mon Feb 27 10:17:47 2012
@@ -21,6 +21,7 @@
import java.util.ArrayList;
import java.util.List;
+import javax.ws.rs.core.MediaType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlRootElement;
@@ -29,7 +30,7 @@
@SuppressWarnings("restriction")
@XmlRootElement(name = "gadget")
-public class Gadget {
+public class Gadget extends RestBean {
@SerializedName("id")
private String m_id;
@@ -45,6 +46,14 @@
@SerializedName("links")
private List<AtomSyndicationLink> m_links;
+ public Gadget() {
+ super();
+ }
+
+ private Gadget(String mimeType) {
+ super(mimeType);
+ }
+
public String getId() {
return m_id;
}
@@ -93,6 +102,24 @@
addLink(link);
}
+ /**
+ * Removes all links matching the specified rel attribute.
+ * @param rel
+ */
+ public void removeLinks(String rel) {
+ if (m_links != null) {
+ List<AtomSyndicationLink> removeLinks = new
ArrayList<AtomSyndicationLink>();
+ for (AtomSyndicationLink link : m_links) {
+ if (rel.equals(link.getRel())) {
+ removeLinks.add(link);
+ }
+ }
+ for (AtomSyndicationLink link : removeLinks) {
+ m_links.remove(link);
+ }
+ }
+ }
+
public void addLink(AtomSyndicationLink link) {
if (m_links == null) {
m_links = new ArrayList<AtomSyndicationLink>();
@@ -100,15 +127,18 @@
m_links.add(link);
}
- public static Gadget getExampleInstance() {
- Gadget gadget = new Gadget();
+ public static Gadget getExample(String mimeType, String httpMethod) {
+ Gadget gadget = new Gadget(mimeType);
gadget.setId("gadget1");
gadget.setSpecification(Specification.getExampleInstance());
gadget.setState(State.getExampleInstance());
- gadget.setUserpreferences(UserPreferencesBean.getExampleInstance());
- String baseUrl =
"http://localhost/rest/dashboards/dashboard/db1/gadgets/gadget1?alt=";;
- gadget.addLink(new AtomSyndicationLink().setHref(baseUrl +
"json").setRel("alternate").setType("application/json"));
- gadget.addLink(new AtomSyndicationLink().setHref(baseUrl +
"xml").setRel("self").setType("application/xml"));
+ if ("GET".equals(httpMethod)) {
+ gadget.setUserpreferences(UserPreferencesBean.getValueExample());
+ }
+ String baseUrl =
"http://localhost/rest/dashboards/db1/gadgets/gadget1";;
+ gadget.addLink(gadget.createLink(baseUrl, MediaType.APPLICATION_JSON));
+ gadget.addLink(gadget.createLink(baseUrl, MediaType.APPLICATION_XML));
return gadget;
}
+
}
Added:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/RestBean.java
==============================================================================
--- (empty file)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/RestBean.java
Mon Feb 27 10:17:47 2012
@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2010, 2011 The Amdatu Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.amdatu.opensocial.gadgetmanagement.bean.dashboard;
+
+import org.amdatu.libraries.utilities.rest.AtomSyndicationLink;
+
+import javax.ws.rs.core.MediaType;
+
+
+
+public class RestBean {
+ private String m_mimeType;
+
+ public RestBean() {
+ }
+
+ protected RestBean(String mimeType) {
+ m_mimeType = mimeType;
+ }
+
+ protected String getRel(String mimeType) {
+ if (m_mimeType.equals(mimeType) || m_mimeType.endsWith(mimeType)) {
+ return "self";
+ } else {
+ return "alternate";
+ }
+ }
+
+ protected AtomSyndicationLink createLink(String baseUrl, String mimeType) {
+ if (MediaType.APPLICATION_JSON.equals(mimeType)) {
+ return new AtomSyndicationLink().setHref(baseUrl +
"?alt=json").setRel(getRel(mimeType)).setType(mimeType);
+ } else if (MediaType.APPLICATION_XML.equals(mimeType)) {
+ return new AtomSyndicationLink().setHref(baseUrl +
"?alt=xml").setRel(getRel(mimeType)).setType(mimeType);
+ }
+ return null;
+ }
+}
Modified:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Specification.java
==============================================================================
---
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Specification.java
(original)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/Specification.java
Mon Feb 27 10:17:47 2012
@@ -75,7 +75,7 @@
spec.setUrl("http://gadgets.nu.nl/nuzakelijk_igoogle.xml";);
spec.setHeight("300");
spec.setTitle("NU zakelijk");
- spec.setUserpreferences(UserPreferencesBean.getExampleInstance());
+ spec.setUserpreferences(UserPreferencesBean.getDefinitionExample());
return spec;
}
}
Added:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/State.java
==============================================================================
--- (empty file)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/bean/dashboard/State.java
Mon Feb 27 10:17:47 2012
@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2010, 2011 The Amdatu Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.amdatu.opensocial.gadgetmanagement.bean.dashboard;
+
+import com.google.gson.annotations.SerializedName;
+
+public class State {
+ @SerializedName("position")
+ private String m_position;
+
+ @SerializedName("positionindex")
+ private int m_positionindex;
+
+ @SerializedName("windowstate")
+ private String m_windowstate;
+
+ @SerializedName("securetoken")
+ private String m_securetoken;
+
+ public String getPosition() {
+ return m_position;
+ }
+
+ public void setPosition(String position) {
+ m_position = position;
+ }
+
+ public int getPositionindex() {
+ return m_positionindex;
+ }
+
+ public void setPositionindex(int index) {
+ m_positionindex = index;
+ }
+
+ public String getWindowstate() {
+ return m_windowstate;
+ }
+
+ public void setWindowstate(String windowstate) {
+ m_windowstate = windowstate;
+ }
+
+ public String getSecuretoken() {
+ return m_securetoken;
+ }
+
+ public void setSecuretoken(String securetoken) {
+ m_securetoken = securetoken;
+ }
+
+ public static State getExampleInstance() {
+ State state = new State();
+ state.setPositionindex(1);
+ state.setPosition("first");
+ state.setSecuretoken("RNlnNnbkaN4g3S2Nn");
+ state.setWindowstate("open");
+ return state;
+ }
+}
Modified:
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/rest/DashboardRESTServiceImpl.java
==============================================================================
---
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/rest/DashboardRESTServiceImpl.java
(original)
+++
trunk/amdatu-opensocial/opensocial-gadgetmanagement/src/main/java/org/amdatu/opensocial/gadgetmanagement/rest/DashboardRESTServiceImpl.java
Mon Feb 27 10:17:47 2012
@@ -88,22 +88,21 @@
}
/**
- * Returns all personalized dashboards for the authenticated user. A
dashboard contains UI properties like
- * the layout of the dashboard and the set of gadgets displayed on that
dashboard.
- *
- * @see org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Dashboards
- * @param expand If expand is not provided or does not equal 'true', the
'spec' element of each gadget only
- * returns the url of the gadgetspec xml. If expand is set to
'true', the XML is retrieved and properties
- * like
- * title, height and userpreferences are added to the gadget spec
element. As this requires an additional
- * HTTP
- * request
- * for each gadget, adding these properties is optional using this
query parameter.
+ * Returns all personalized dashboards for an authenticated user. A user
may save multiple dashboards, each
+ * one of them identified by a unique id. A dashboard contains UI
properties like the name and layout of the
+ * dashboard and the set of gadgets displayed on that dashboard.
+ *
+ * @see
org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Dashboards#getExample
+ * @param expand If the expand parameter is not provided or does not equal
'true', the dashboards are
+ * returned without the gadgets they contain. If the expand query
parameter is set to 'true', the gadgets are
+ * returned including all information retrieved from the
specification XML (title, height and userpreference
+ * definitions), a generated secure token and the userpreference
values saved by the authenticated user for
+ * each gadget. As this requires an additional HTTP request for
each gadget, adding these properties is
+ * optional using this query parameter.
* @param request The HTTP request
* @return <ul>
* <li>200 (OK) : The dashboards were returned successfully.</li>
- * <li>401 (UNAUTHORIZED) : The user is not authenticated so no
dashboards are returned.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated so no
dashboards could be returned.</li>
* </ul>
*/
@GET
@@ -131,29 +130,27 @@
}
}
catch (Exception e) {
- return get500(e, "Error 500 - An error has occurred while loading
dashboards");
+ return get500(e, "Error 500 - An error has occurred while loading
dashboards.");
}
}
/**
- * Creates a new personalized dashboard with the provided properties (like
layout and gadgets displayed on it).
- * The id of the new dashboard will be generated and returned in the
result. The user must be authenticated,
+ * Creates a new personalized dashboard with the provided name. The id of
the new dashboard will be
+ * generated and returned in the result. The user must be authenticated,
* the new dashboard will be appended to the existing list of personal
dashboards.
*
- * @see org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Dashboard
- * @param id The id of the dashboard to write the properties for
- * @param expand If expand is not provided or does not equal 'true', the
'spec' element of each gadget only
- * returns the url of the gadgetspec xml. If expand is set to
'true', the XML is retrieved and properties
- * like
- * title, height and userpreferences are added to the gadget spec
element. As this requires an additional
- * HTTP
- * request
- * for each gadget, adding these properties is optional using this
query parameter.
+ * @see
org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Dashboard#getExample
+ * @param name The name of the dashboard to create.
+ * @param expand If the expand parameter is not provided or does not equal
'true', the dashboards are
+ * returned without the gadgets they contain. If the expand query
parameter is set to 'true', the gadgets are
+ * returned including all information retrieved from the
specification XML (title, height and userpreference
+ * definitions), a generated secure token and the userpreference
values saved by the authenticated user for
+ * each gadget. As this requires an additional HTTP request for
each gadget, adding these properties is
+ * optional using this query parameter.
* @param request The HTTP servlet request
* @return <ul>
* <li>200 (OK) : The created dashboard is returned.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated so no
dashboard could be created.</li>
* </ul>
*/
@POST
@@ -182,23 +179,32 @@
return get401("Error 401 - Unauthorized. Only authenticated users
can create a dashboard.");
}
catch (Exception e) {
- return get500(e, "Error 500 - An error has occurred while creating
dashboard");
+ return get500(e, "Error 500 - An error has occurred while creating
dashboard.");
}
}
/**
* Returns a single personalized dashboard for the authenticated user. A
dashboard contains UI properties
- * like the layout of the dashboard and the set of gadgets displayed on
that dashboard.
- * If the user is not authenticated or did not yet save a dashboard, a
default dashboard will be returned.
- *
- * @see org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Dashboard
- * @param dashboardid The id of the dashboard to retrieve
+ * like the name and layout of the dashboard and the set of gadgets
displayed on that dashboard.
+ * If the user is authenticated or did not save a dashboard before, the
default dashboard will be returned.
+ * The id of the default dashboard is 'default' and is the only dashboard
that can be retrieved by
+ * unauthenticated users. The default dashboard contains gadgets that have
been marked to appear on this default
+ * dashboard in the gadget store. Usually, this is only the login gadget.
+ *
+ * @see
org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Dashboard#getExample
+ * @param dashboardid The id of the dashboard to retrieve.
+ * @param expand If the expand parameter is not provided or does not equal
'true', the dashboards are
+ * returned without the gadgets they contain. If the expand query
parameter is set to 'true', the gadgets are
+ * returned including all information retrieved from the
specification XML (title, height and userpreference
+ * definitions), a generated secure token and the userpreference
values saved by the authenticated user for
+ * each gadget. As this requires an additional HTTP request for
each gadget, adding these properties is
+ * optional using this query parameter.
* @param request The HTTP request
* @return <ul>
* <li>200 (OK) : The dashboard was returned successfully.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>404 (NOT FOUND) : returned in case the dashboard could not
be found.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated and
tried to retrieve a dashboard other then the
+ * default dashboard.</li>
+ * <li>404 (NOT FOUND) : No dashboard with the specified id
exists.</li>
* </ul>
*/
@GET
@@ -241,24 +247,24 @@
return get401("Error 401 - Unauthorized. Only authenticated users
can retrieve dashboards.");
}
catch (Exception e) {
- return get500(e, "Error 500 - An error has occurred while loading
dashboard with id '" + dashboardid + "'");
+ return get500(e, "Error 500 - An error has occurred while loading
dashboard with id '" + dashboardid + "'.");
}
}
/**
- * Creates a new dashboard with the specified id and properties or
overwrites the existing dashboard
- * with the specified id. The user must be authenticated.
+ * Saves the dashboard with the specified id. If no dashboard with this id
existed yet, it is created. If a
+ * dashboard with this id already existed, it is overwritten. The user
must be authenticated to be able to
+ * save dashboards.
*
- * Example: PUT /rest/dashboards/dashboard_01 [json expression]
- *
- * @param dashboardid The id of the dashboard to write the properties for
+ * @see
org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Dashboard#getExample
+ * @param dashboardid The id of the dashboard to write the properties for.
* @param request The HTTP servlet request
* @return <ul>
- * <li>200 (OK) : The dashboard was created or updated
successfully.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>403 (FORBIDDEN) : returned in case the user tries to update
the default dashboard, which is not
- * allowed.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>200 (OK) : The dashboard was created or updated
successfully. A 'created successfully' message is
+ * returned.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated, only
authenticated users can save
+ * dashboards.</li>
+ * <li>403 (FORBIDDEN) : The user tried to update the default
dashboard, which is not allowed.</li>
* </ul>
*/
@PUT
@@ -303,22 +309,21 @@
return get401("Error 401 - Unauthorized. Only authenticated users
can save a dashboard.");
}
catch (Exception e) {
- return get500(e, "Error 500 - An error has occurred while saving
dashboard with id '" + dashboardid + "'");
+ return get500(e, "Error 500 - An error has occurred while saving
dashboard with id '" + dashboardid + "'.");
}
}
/**
* Deletes the dashboard with the specified identifier.
*
- * @param dashboardid The id of the dashboard to delete
+ * @param dashboardid The id of the dashboard to delete.
* @param request The HTTP servlet request
* @return <ul>
- * <li>200 (OK) : The dashboard was deleted successfully.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>403 (FORBIDDEN) : returned in case the user tries to delete
the default dashboard, which is not
- * allowed.</li>
- * <li>404 (NOT FOUND) : returned in case the dashboard could not
be found.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>200 (OK) : The dashboard was deleted successfully. A
'deleted successfully' message is returned.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated, only
authenticated users can delete
+ * dashboards.</li>
+ * <li>403 (FORBIDDEN) : The user tried to delete the default
dashboard, which is not allowed.</li>
+ * <li>404 (NOT FOUND) : No dashboard with the specified id
exists.</li>
* </ul>
*/
@DELETE
@@ -345,105 +350,47 @@
+ "' removed successfully.");
}
}
- return get404("No dashboard exists with id '" + dashboardid);
+ return get404("No dashboard exists with id '" + dashboardid +
"'.");
}
return get401("Error 401 - Unauthorized. Only authenticated users
can save a dashboard.");
}
catch (Exception e) {
- return get500(e, "Error 500 - An error has occurred while deleting
dashboard with id '" + dashboardid + "'");
- }
- }
-
- /**
- * Returns a particular gadget from the specified dashboard.
- *
- * @see org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Gadget
- * @param dashboardid The id of the dashboard to retrieve the gadget from
- * @param gadgetid The id of the gadget to retrieve
- * @param expand If expand is not provided or does not equal 'true', the
'spec' element of each gadget only
- * returns the url of the gadgetspec xml. If expand is set to
'true', the XML is retrieved and properties
- * like
- * title, height and userpreferences are added to the gadget spec
element. As this requires an additional
- * HTTP
- * request
- * @param request The HTTP servlet request
- * @return <ul>
- * <li>200 (OK) : The specified gadget is returned.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>404 (NOT FOUND) : returned in case the dashboard and/or
gadget could not be found.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
- * </ul>
- */
- @GET
- @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
- @Path("/{dashboardid}/gadgets/{gadgetid}")
- public Response getGadget(@PathParam("dashboardid") final String
dashboardid,
- @PathParam("gadgetid") final String gadgetid, @QueryParam("expand")
final String expand,
- @Context final HttpServletRequest request, @Context final HttpHeaders
headers) {
- try {
- if (!DEFAULT_DBID.equals(dashboardid) && !isAuthorized(request)) {
- return get401("Error 401 - Unauthorized. Only authenticated
users can retrieve gadgets.");
- }
- Dashboard dashboard = null;
- if (DEFAULT_DBID.equals(dashboardid)) {
- // Special case: the default dashboard is requested
- dashboard = getDefaultDashboard(request);
- }
- else {
- User user = getUserFromViewer(request);
- Dashboards dashboards = load(user);
- dashboard = findDashboard(dashboards, dashboardid);
- }
- if (dashboard != null) {
- // Find the gadget
- Gadget gadget = findGadget(dashboard, gadgetid);
- if (gadget != null) {
- m_dbProcessor.prepareToReturn(dashboard, gadget,
"true".equals(expand), request, headers, false);
- return get200(gadget);
- }
- }
-
- return get404("No gadget exists with id '" + gadgetid + "' on
dashboard with id '"
- + dashboardid
- + "'");
- }
- catch (Exception e) {
- return get500(e, "Error 500 - An error has occurred while
retrieving gadget with id '" + gadgetid + "'");
+ return get500(e, "Error 500 - An error has occurred while deleting
dashboard with id '" + dashboardid
+ + "'.");
}
}
/**
* Adds a gadget to a personalized dashboard. A unique (within the
dashboard) identifier is generated and
- * assigned to the gadget and atom links are added.
+ * assigned to the gadget.
*
- * @see org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Gadget
- * @param expand If expand is not provided or does not equal 'true', the
'spec' element of each gadget only
- * returns the url of the gadgetspec xml. If expand is set to
'true', the XML is retrieved and properties
- * like
- * title, height and userpreferences are added to the gadget spec
element. As this requires an additional
- * HTTP
- * request
- * @param dashboardid The id of the personalized dashboard to append the
gadget to
- * @param gadget The properties of the gadget to add
+ * @see
org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Gadget#getExample
+ * @param expand If the expand parameter is not provided or does not equal
'true', the dashboards are
+ * returned without the gadgets they contain. If the expand query
parameter is set to 'true', the gadgets are
+ * returned including all information retrieved from the
specification XML (title, height and userpreference
+ * definitions), a generated secure token and the userpreference
values saved by the authenticated user for
+ * each gadget. As this requires an additional HTTP request for
each gadget, adding these properties is
+ * optional using this query parameter.
+ * @param dashboardid The id of the dashboard to append the gadget to.
+ * @param url The gadget specification URL.
* @param request The HTTP servlet request
* @return <ul>
* <li>200 (OK) : The gadget was added successfully.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>403 (FORBIDDEN) : returned in case the user tries to append
a gadget to the default dashboard, which
- * is not allowed.</li>
- * <li>404 (NOT FOUND) : returned in case no dashboard with the
specified id exists.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated, only
authenticated users can append gadgets to
+ * dashboards (they own).</li>
+ * <li>403 (FORBIDDEN) :The user tried to append a gadget to the
default dashboard, which is not
+ * allowed.</li>
+ * <li>404 (NOT FOUND) : No dashboard with the specified id
exists.</li>
* </ul>
*/
@POST
@Consumes({MediaType.APPLICATION_FORM_URLENCODED})
- @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
+ @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Path("/{dashboardid}/gadgets")
public Response createGadget(@PathParam("dashboardid") final String
dashboardid,
- @FormParam("url") final String url,
- @QueryParam("expand") final String expand, @Context final
HttpServletRequest request,
- @Context final HttpHeaders headers) {
+ @FormParam("url") final String url, @QueryParam("expand") final String
expand,
+ @Context final HttpServletRequest request, @Context final HttpHeaders
headers) {
try {
if (DEFAULT_DBID.equals(dashboardid)) {
return get403("Error 403 - Forbidden. Gadgets cannot be added
to the default dashboard.");
@@ -480,18 +427,77 @@
}
/**
- * Deletes the gadget with the specified identifier.
+ * Returns a single gadget from the dashboard with the specified id.
*
- * @param dashboardid The id of the dashboard to delete
- * @param gadgetid The id of the gadget to delete
- * @param request The HTTP servlet request
+ * @see
org.amdatu.opensocial.gadgetmanagement.bean.dashboard.Gadget#getExample
+ * @param dashboardid The id of the dashboard to retrieve the gadget from.
+ * @param gadgetid The id of the gadget to retrieve.
+ * @param expand If the expand parameter is not provided or does not equal
'true', the dashboards are
+ * returned without the gadgets they contain. If the expand query
parameter is set to 'true', the gadgets are
+ * returned including all information retrieved from the
specification XML (title, height and userpreference
+ * definitions), a generated secure token and the userpreference
values saved by the authenticated user for
+ * each gadget. As this requires an additional HTTP request for
each gadget, adding these properties is
+ * optional using this query parameter.
+ * @param request The HTTP servlet request.
+ * @return <ul>
+ * <li>200 (OK) : The specified gadget is returned.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated.
Unauthenticated users can only retrieve the
+ * default dashboard.</li>
+ * <li>404 (NOT FOUND) : The gadget could not be retrieved since
either {dashboardid} does
+ * not refer to an existing dashboard or {gadgetid} does not refer
to an existing gadget.</li>
+ * </ul>
+ */
+ @GET
+ @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
+ @Path("/{dashboardid}/gadgets/{gadgetid}")
+ public Response getGadget(@PathParam("dashboardid") final String
dashboardid,
+ @PathParam("gadgetid") final String gadgetid, @QueryParam("expand")
final String expand,
+ @Context final HttpServletRequest request, @Context final HttpHeaders
headers) {
+ try {
+ if (!DEFAULT_DBID.equals(dashboardid) && !isAuthorized(request)) {
+ return get401("Error 401 - Unauthorized. Only authenticated
users can retrieve gadgets.");
+ }
+ Dashboard dashboard = null;
+ if (DEFAULT_DBID.equals(dashboardid)) {
+ // Special case: the default dashboard is requested
+ dashboard = getDefaultDashboard(request);
+ }
+ else {
+ User user = getUserFromViewer(request);
+ Dashboards dashboards = load(user);
+ dashboard = findDashboard(dashboards, dashboardid);
+ }
+ if (dashboard != null) {
+ // Find the gadget
+ Gadget gadget = findGadget(dashboard, gadgetid);
+ if (gadget != null) {
+ m_dbProcessor.prepareToReturn(dashboard, gadget,
"true".equals(expand), request, headers, false);
+ return get200(gadget);
+ }
+ }
+
+ return get404("No gadget exists with id '" + gadgetid + "' on
dashboard with id '"
+ + dashboardid + "'");
+ }
+ catch (Exception e) {
+ return get500(e, "Error 500 - An error has occurred while
retrieving gadget with id '" + gadgetid + "'");
+ }
+ }
+
+ /**
+ * Deletes a single gadget from the specified dashboard.
+ *
+ * @param dashboardid The id of the dashboard to delete the gadget from.
+ * @param gadgetid The id of the gadget to delete.
+ * @param request The HTTP servlet request.
* @return <ul>
- * <li>200 (OK) : The gadget was deleted successfully.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>403 (FORBIDDEN) : returned in case the user tries to delete
a gadget from the default dashboard,
+ * <li>200 (OK) : The gadget was deleted successfully from the
dashboard.</li>
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated, noly
authenticated users can delete
+ * gadgets from (yjeir) dashboards.</li>
+ * <li>403 (FORBIDDEN) : The user tried to delete a gadget from
the default dashboard,
* which is not allowed.</li>
- * <li>404 (NOT FOUND) : returned in case the dashboard and/or
gadget could not be found.</li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>404 (NOT FOUND) : The gadget could not be deleted since
either {dashboardid} does
+ * not refer to an existing dashboard or {gadgetid} does not refer
to an existing gadget.</li>
* </ul>
*/
@DELETE
@@ -510,15 +516,15 @@
if (dashboards != null) {
Dashboard dashboard = findDashboard(dashboards,
dashboardid);
if (dashboard != null) {
- Gadget gadget = findGadget(dashboard, gadgetid);
- if (gadget != null) {
- dashboard.getGadgets().remove(gadget);
- m_dbProcessor.prepareToPersist(dashboards);
- save(user, dashboards);
-
- return get200("Dashboard '" + dashboardid + "' for
user '" + user.getName()
- + "' removed successfully.");
- }
+ Gadget gadget = findGadget(dashboard, gadgetid);
+ if (gadget != null) {
+ dashboard.getGadgets().remove(gadget);
+ m_dbProcessor.prepareToPersist(dashboards);
+ save(user, dashboards);
+
+ return get200("Dashboard '" + dashboardid + "' for
user '" + user.getName()
+ + "' removed successfully.");
+ }
}
}
return get404("No dashboard and/or gadget exists with
dashboard id '" + dashboardid
@@ -534,22 +540,23 @@
}
/**
- * Returns the user preferences of a single gadget on a specific
dashboard. If the user
- * that invoked the request is authenticated (determined from the session
cookie), the default values
- * of the user preferences from the gadgetSpec of this gadget will be
overruled by the users personal settings.
- * If the user is not authenticated
- *
- * @see org.amdatu.opensocial.gadgetmanagement.UserPreferencesBean
- * @param dashboardid The id of the dashboard to retrieve the widget from
- * @param gadgetid The id of the widget to retrieve the user preferences
for
- * @param request The http request
+ * Returns the user preference values of a single gadget on a specific
dashboard. Note that the user
+ * preference definitions are returned as part of the specification. This
resource only holds user
+ * preference values set by this user. A value contains a name and a
value. The name macthes one
+ * on one with the name of a user preference definition.
+ *
+ * @see
org.amdatu.opensocial.gadgetmanagement.UserPreferencesBean#getValueExample
+ * @param dashboardid The id of the dashboard to retrieve the
userpreferences from.
+ * @param gadgetid The id of the gadget to retrieve the user preferences
from.
+ * @param request The http request.
* @return <ul>
* <li>200 (OK) : The user preferences were returned
successfully.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>
- * <li>404 (NOT FOUND) : The user preferences could not be
retrieved since either the widgetid
- * does not refer to an existing widget, or the gadgetspec could
not be retrieved from the
- * specified uri </li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>204 (NO CONTENT) : The dashboard and gadget could be
resolved, but the user did not yet
+ * save any preferences for this gadget.
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated and did
not retrieve userpreferences
+ * for the default dashboard (which is allowed by unauthenticated
users).</li>
+ * <li>404 (NOT FOUND) : The user preferences could not be
retrieved since either {dashboardid} does
+ * not refer to an existing dashboard or {gadgetid} does not refer
to an existing gadget.</li>
* </ul>
*/
@GET
@@ -580,7 +587,7 @@
if (gadget.getUserpreferences() != null) {
return get200(gadget.getUserpreferences());
}
- return get204("No UserPrefs saved yet for this user");
+ return get204("No userpreferences saved yet for this
user");
}
else {
return get404("No gadget exists with id '" + gadgetid
+ "'");
@@ -600,24 +607,22 @@
}
/**
- * Returns the user preferences of a single gadget on a specific
dashboard. If the user
- * that invoked the request is authenticated (determined from the session
cookie), the default values
- * of the user preferences from the gadgetSpec of this gadget will be
overruled by the users personal settings.
- * If the user is not authenticated
- *
- * @see org.amdatu.opensocial.gadgetmanagement.UserPreferencesBean
- * @param dashboardid The id of the dashboard to retrieve the widget from
- * @param gadgetid The id of the widget to retrieve the user preferences
for
- * @param request The http request
+ * Sets the user preference values of a single gadget on a specific
dashboard. Note that the user
+ * preference definitions are returned as part of the specification. This
resource only holds user
+ * preference values set by this user. A value contains a name and a
value. The name macthes one
+ * on one with the name of a user preference definition.
+ *
+ * @see
org.amdatu.opensocial.gadgetmanagement.UserPreferencesBean#getValueExample
+ * @param dashboardid The id of the dashboard to retrieve the gadget from.
+ * @param gadgetid The id of the gadget to retrieve the user from.
+ * @param request The http request.
* @return <ul>
* <li>200 (OK) : The user preferences were saved
successfully.</li>
- * <li>401 (UNAUTHORIZED) : returned in case the user is not
authenticated.</li>\
- * <li>403 (FORBIDDEN) : returned in case the user tries to update
userpreferences for the default
+ * <li>401 (UNAUTHORIZED) : The user is not authenticated.</li>
+ * <li>403 (FORBIDDEN) : The user tried to update userpreferences
for the default
* dashboard, which is not allowed.</li>
- * <li>404 (NOT FOUND) : The user preferences could not be
retrieved since either the widgetid
- * does not refer to an existing widget, or the gadgetspec could
not be retrieved from the
- * specified uri </li>
- * <li>500 (INTERNAL SERVER ERROR) : returned in case an
unexpected internal error occurred.</li>
+ * <li>404 (NOT FOUND) : The user preferences could not be
retrieved since either {dashboardid} does
+ * not refer to an existing dashboard or {gadgetid} does not refer
to an existing gadget.</li>
* </ul>
*/
@PUT
@@ -656,11 +661,11 @@
+ "' saved successfully.");
}
else {
- return get404("No gadget exists with id '" + gadgetid
+ "'");
+ return get404("No gadget exists with id '" + gadgetid
+ "'.");
}
}
else {
- return get404("No dashboard exists with id '" +
dashboardid + "'");
+ return get404("No dashboard exists with id '" +
dashboardid + "'.");
}
}
return get401("Error 401 - Unauthorized. Only authenticated users
can save user preferences.");
_______________________________________________
Amdatu-commits mailing list
[email protected]
http://lists.amdatu.org/mailman/listinfo/amdatu-commits
