for the user-level
+ * documentation of this feature.
+ *
+ *
+ * This mechanism is implemented by marking model objects
+ * by using {@link ExposedBean} and {@link Exposed} annotations.
+ * Those annotation together designates what properties are exposed
+ * to those remote APIs.
+ *
+ *
+ * So generally speaking the model classes only need to annotate themselves
+ * by those annotations to get their data exposed to the remote API.
+ *
+ * @since 1.101
+ */
+package hudson.api;
+
+import hudson.model.ModelObject;
\ No newline at end of file
diff --git a/core/src/main/java/hudson/model/AbstractBuild.java b/core/src/main/java/hudson/model/AbstractBuild.java
index 2d52b4b80c..c62e5927cc 100644
--- a/core/src/main/java/hudson/model/AbstractBuild.java
+++ b/core/src/main/java/hudson/model/AbstractBuild.java
@@ -3,6 +3,7 @@ package hudson.model;
import hudson.Launcher;
import hudson.Proc.LocalProc;
import hudson.Util;
+import hudson.api.Exposed;
import hudson.tasks.Fingerprinter.FingerprintAction;
import hudson.tasks.test.AbstractTestResultAction;
import hudson.maven.MavenBuild;
@@ -86,6 +87,7 @@ public abstract class AbstractBuild
,R extends Abs
/**
* Returns the name of the slave it was built on, or null if it was the master.
*/
+ @Exposed(name="builtOn")
public String getBuiltOnStr() {
return builtOn;
}
diff --git a/core/src/main/java/hudson/model/AbstractItem.java b/core/src/main/java/hudson/model/AbstractItem.java
index d2292cc563..c769d54614 100644
--- a/core/src/main/java/hudson/model/AbstractItem.java
+++ b/core/src/main/java/hudson/model/AbstractItem.java
@@ -2,6 +2,8 @@ package hudson.model;
import hudson.XmlFile;
import hudson.Util;
+import hudson.api.Exposed;
+import hudson.api.ExposedBean;
import java.io.File;
import java.io.IOException;
@@ -9,6 +11,7 @@ import java.util.Collection;
import org.kohsuke.stapler.StaplerRequest;
import org.kohsuke.stapler.StaplerResponse;
+import org.kohsuke.stapler.Stapler;
import javax.servlet.ServletException;
@@ -19,6 +22,7 @@ import javax.servlet.ServletException;
*/
// Item doesn't necessarily have to be Actionable, but
// Java doesn't let multiple inheritance.
+@ExposedBean
public abstract class AbstractItem extends Actionable implements Item {
/**
* Project name.
@@ -37,10 +41,12 @@ public abstract class AbstractItem extends Actionable implements Item {
doSetName(name);
}
+ @Exposed(visibility=2)
public String getName() {
return name;
}
+ @Exposed
public String getDisplayName() {
return getName();
}
@@ -57,6 +63,7 @@ public abstract class AbstractItem extends Actionable implements Item {
/**
* Gets the project description HTML.
*/
+ @Exposed
public String getDescription() {
return description;
}
@@ -114,6 +121,14 @@ public abstract class AbstractItem extends Actionable implements Item {
return getParent().getUrlChildPrefix()+'/'+getName()+'/';
}
+ @Exposed(visibility=2,name="url")
+ public final String getAbsoluteUrl() {
+ StaplerRequest request = Stapler.getCurrentRequest();
+ if(request==null)
+ throw new IllegalStateException("Not processing a HTTP request");
+ return request.getRootPath()+'/'+getUrl();
+ }
+
/**
* Save the settings to a file.
*/
diff --git a/core/src/main/java/hudson/model/Api.java b/core/src/main/java/hudson/model/Api.java
index fa22165861..b7c79a03a4 100644
--- a/core/src/main/java/hudson/model/Api.java
+++ b/core/src/main/java/hudson/model/Api.java
@@ -1,34 +1,27 @@
package hudson.model;
-import com.thoughtworks.xstream.XStream;
-import com.thoughtworks.xstream.mapper.MapperWrapper;
-import hudson.util.XStream2;
-import net.sf.json.JSONObject;
-import net.sf.json.util.JSONBuilder;
+import hudson.api.DataWriter;
+import hudson.api.Exposed;
+import hudson.api.Parser;
+import hudson.api.ParserBuilder;
import org.kohsuke.stapler.StaplerRequest;
import org.kohsuke.stapler.StaplerResponse;
-import java.beans.Introspector;
import java.io.IOException;
import java.io.PrintWriter;
-import java.lang.reflect.Field;
-import java.lang.reflect.Modifier;
-import java.net.URL;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.HashSet;
-import java.util.Map;
-import java.util.Set;
-import java.util.Calendar;
+import java.io.Writer;
+import java.util.Stack;
+import java.beans.Introspector;
/**
* Used to expose remote access API for ".../api/"
*
* @author Kohsuke Kawaguchi
+ * @see Exposed
*/
public class Api extends AbstractModelObject {
/**
- * Value bean to be exposed as XML/JSON/etc.
+ * Model object to be exposed as XML/JSON/etc.
*/
private final Object bean;
@@ -43,140 +36,143 @@ public class Api extends AbstractModelObject {
/**
* Exposes the bean as XML.
*/
- public void doXml(StaplerRequest req, StaplerResponse rsp) throws IOException {
+ public void doXml(StaplerRequest req, final StaplerResponse rsp) throws IOException {
rsp.setContentType("application/xml;charset=UTF-8");
- RestXStream.INSTANCE.toXML(bean, rsp.getWriter());
+
+ write(new DataWriter() {
+ private String name = Introspector.decapitalize(bean.getClass().getSimpleName());
+ private final Stack objectNames = new Stack();
+ private final Stack arrayState = new Stack();
+ private final Writer out = rsp.getWriter();
+ public boolean isArray;
+
+ public void name(String name) {
+ this.name = name;
+ }
+
+ public void valuePrimitive(Object v) throws IOException {
+ value(v.toString());
+ }
+
+ public void value(String v) throws IOException {
+ String n = adjustName();
+ out.write('<'+n+'>');
+ out.write(v);
+ out.write(""+n+'>');
+ }
+
+ public void valueNull() {
+ // use absence to indicate null.
+ }
+
+ public void startArray() {
+ // use repeated element to display array
+ // this means nested arrays are not supported
+ isArray = true;
+ }
+
+ public void endArray() {
+ isArray = false;
+ }
+
+ public void startObject() throws IOException {
+ objectNames.push(name);
+ arrayState.push(isArray);
+ out.write('<'+adjustName()+'>');
+ }
+
+ public void endObject() throws IOException {
+ name = objectNames.pop();
+ out.write(""+adjustName()+'>');
+ isArray = arrayState.pop();
+ }
+
+ /**
+ * Returns the name to be used as an element name
+ * by considering {@link #isArray}
+ */
+ private String adjustName() {
+ if(isArray) {
+ if(name.endsWith("s"))
+ return name.substring(0,name.length()-1);
+ }
+ return name;
+ }
+ });
}
/**
* Exposes the bean as JSON.
*/
- public void doJson(StaplerRequest req, StaplerResponse rsp) throws IOException {
+ public void doJson(StaplerRequest req, final StaplerResponse rsp) throws IOException {
rsp.setContentType("text/javascript;charset=UTF-8");
String pad = req.getParameter("jsonp");
PrintWriter w = rsp.getWriter();
if(pad!=null) w.print(pad+'(');
- JSONSerializer.write(bean,new JSONBuilder(w));
+
+ write(new DataWriter() {
+ private boolean needComma;
+ private final Writer out = rsp.getWriter();
+
+ public void name(String name) throws IOException {
+ comma();
+ out.write(name+':');
+ needComma = false;
+ }
+
+ private void data(String v) throws IOException {
+ comma();
+ out.write(v);
+ }
+
+ private void comma() throws IOException {
+ if(needComma) out.write(',');
+ needComma = true;
+ }
+
+ public void valuePrimitive(Object v) throws IOException {
+ data(v.toString());
+ }
+
+ public void value(String v) throws IOException {
+ data('\"'+v+'\"');
+ }
+
+ public void valueNull() throws IOException {
+ data("null");
+ }
+
+ public void startArray() throws IOException {
+ comma();
+ out.write('[');
+ needComma = false;
+ }
+
+ public void endArray() throws IOException {
+ out.write(']');
+ needComma = true;
+ }
+
+ public void startObject() throws IOException {
+ comma();
+ out.write('{');
+ needComma=false;
+ }
+
+ public void endObject() throws IOException {
+ out.write('}');
+ needComma=true;
+ }
+ });
+
if(pad!=null) w.print(')');
}
- /**
- * {@link XStream} customized for writing XML for the REST API.
- *
- * @author Kohsuke Kawaguchi
- */
- private static class RestXStream extends XStream2 {
- private RestXStream() {
- setMode(NO_REFERENCES);
- registerConverter(Result.conv);
- }
-
- @Override
- protected MapperWrapper wrapMapper(MapperWrapper next) {
- return new MapperWrapper(next) {
- // always use the short name
- public String serializedClass(Class type) {
- return Introspector.decapitalize(type.getSimpleName());
- }
-
- // don't serialize the outer class
- public boolean shouldSerializeMember(Class definedIn, String fieldName) {
- return !fieldName.startsWith("this$") && !fieldName.startsWith("val$")
- && super.shouldSerializeMember(definedIn, fieldName);
- }
- };
- }
-
- static final RestXStream INSTANCE = new RestXStream();
+ private void write(DataWriter writer) throws IOException {
+ Parser p = parserBuilder.get(bean.getClass());
+ p.writeTo(bean,writer);
}
- /**
- * Works like {@link JSONObject#fromBean(Object)} except
- * this uses fields instead of properties.
- *
- * @author Kohsuke Kawaguchi
- */
- private static class JSONSerializer {
-
- private static final Set LEAF_TYPES = new HashSet(Arrays.asList(
- String.class,
- URL.class,
- Boolean.class,
- Integer.class,
- Short.class,
- Long.class,
- Float.class,
- Double.class
- ));
-
- public static void write(Object bean, JSONBuilder builder) {
- if(bean==null) {
- builder.value(null);
- return;
- }
-
- Class c = bean.getClass();
-
- if(LEAF_TYPES.contains(c)) {
- builder.value(bean);
- return;
- }
- if(c.getComponentType()!=null) { // array
- builder.array();
- for (Object item : (Object[])bean)
- write(item,builder);
- builder.endArray();
- return;
- }
- if(bean instanceof Collection) {
- builder.array();
- for (Object item : (Collection) bean)
- write(item,builder);
- builder.endArray();
- return;
- }
- if(bean instanceof Map) {
- builder.object();
- for (Map.Entry e : ((Map,?>) bean).entrySet()) {
- builder.key(e.getKey().toString());
- write(e.getValue(),builder);
- }
- return;
- }
- if(bean instanceof Calendar) {
- builder.value(((Calendar)bean).getTimeInMillis());
- return;
- }
- if(bean instanceof Enum) {
- builder.value(bean);
- return;
- }
-
- // otherwise handle it as a bean
- writeBean(builder, bean);
- }
-
- private static void writeBean(JSONBuilder builder, Object bean) {
- builder.object();
-
- for( Field f : bean.getClass().getFields() ) {
- try {
- if(Modifier.isStatic(f.getModifiers()))
- continue;
- f.setAccessible(true);
- Object value = f.get(bean);
- if(value!=null) {
- builder.key(f.getName());
- write(value,builder);
- }
- } catch (IllegalAccessException e) {
- // impossible given that this is a public field
- throw new Error(e);
- }
- }
-
- builder.endObject();
- }
- }
+ private static final ParserBuilder parserBuilder = new ParserBuilder();
}
diff --git a/core/src/main/java/hudson/model/Build.java b/core/src/main/java/hudson/model/Build.java
index e2afc7efa4..84175a1932 100644
--- a/core/src/main/java/hudson/model/Build.java
+++ b/core/src/main/java/hudson/model/Build.java
@@ -88,16 +88,7 @@ public final class Build extends AbstractBuild {
}
public Api getApi(final StaplerRequest req) {
- // TODO: think of a way to compose this to push some of this up
- // the inheritance tree.
- class build {
- public int number = getNumber();
- public Calendar timestamp = getTimestamp();
- public String builtOn = getBuiltOnStr();
- public Result result = getResult();
- public long duration = getDuration();
- }
- return new Api(new build());
+ return new Api(this);
}
//
diff --git a/core/src/main/java/hudson/model/Hudson.java b/core/src/main/java/hudson/model/Hudson.java
index 04f36f8c61..054e1ea986 100644
--- a/core/src/main/java/hudson/model/Hudson.java
+++ b/core/src/main/java/hudson/model/Hudson.java
@@ -13,6 +13,7 @@ import hudson.TcpSlaveAgentListener;
import hudson.Util;
import static hudson.Util.fixEmpty;
import hudson.XmlFile;
+import hudson.api.Exposed;
import hudson.model.Descriptor.FormException;
import hudson.model.listeners.ItemListener;
import hudson.model.listeners.JobListener;
@@ -38,9 +39,9 @@ import hudson.triggers.Triggers;
import hudson.util.CopyOnWriteList;
import hudson.util.CopyOnWriteMap;
import hudson.util.FormFieldValidator;
-import hudson.util.XStream2;import hudson.util.MultipartFormDataParser;
+import hudson.util.MultipartFormDataParser;
+import hudson.util.XStream2;
import org.apache.commons.fileupload.FileItem;
-import org.apache.commons.fileupload.FileUploadException;
import org.apache.commons.fileupload.disk.DiskFileItemFactory;
import org.apache.commons.fileupload.servlet.ServletFileUpload;
import org.kohsuke.stapler.StaplerRequest;
@@ -404,6 +405,7 @@ public final class Hudson extends View implements ItemGroup, Node
*
* @see #getAllItems(Class)
*/
+ @Exposed(name="jobs")
public List getItems() {
return new ArrayList(items.values());
}
@@ -1366,33 +1368,7 @@ public final class Hudson extends View implements ItemGroup, Node
}
public Api getApi(final StaplerRequest req) {
- class hudson {
- public List jobs = new ArrayList();
-
- class job {
- public String name;
- public String url;
- public BallColor color;
- public Integer lastBuild;
-
- public job(TopLevelItem item) {
- this.name = item.getName();
- this.url = req.getRootPath()+'/'+item.getUrl();
- if (item instanceof Job) {
- Job job = (Job) item;
- color = job.getIconColor();
- lastBuild =job.getLastBuild()!=null ? job.getLastBuild().getNumber() : null;
- }
- }
- }
-
- hudson() {
- for (TopLevelItem item : getItems())
- jobs.add(new job(item));
- }
- }
-
- return new Api(new hudson());
+ return new Api(this);
}
diff --git a/core/src/main/java/hudson/model/Item.java b/core/src/main/java/hudson/model/Item.java
index d2f73bdf01..b86cb37197 100644
--- a/core/src/main/java/hudson/model/Item.java
+++ b/core/src/main/java/hudson/model/Item.java
@@ -1,5 +1,7 @@
package hudson.model;
+import org.kohsuke.stapler.StaplerRequest;
+
import java.io.IOException;
import java.util.Collection;
@@ -87,6 +89,18 @@ public interface Item extends PersistenceRoot {
*/
String getShortUrl();
+ /**
+ * Returns the absolute URL of this item. This relies on the current
+ * {@link StaplerRequest} to figure out what the host name is,
+ * so can be used only during processing client requests.
+ *
+ * @return
+ * absolute URL.
+ * @throws IllegalStateException
+ * if the method is invoked outside the HTTP request processing.
+ */
+ String getAbsoluteUrl();
+
/**
* Called right after when a {@link Item} is loaded from disk.
* This is an opporunity to do a post load processing.
diff --git a/core/src/main/java/hudson/model/Job.java b/core/src/main/java/hudson/model/Job.java
index 04d3a479cc..83c07364c8 100644
--- a/core/src/main/java/hudson/model/Job.java
+++ b/core/src/main/java/hudson/model/Job.java
@@ -2,6 +2,8 @@ package hudson.model;
import hudson.ExtensionPoint;
import hudson.Util;
+import hudson.api.Exposed;
+import hudson.api.ExposedBean;
import hudson.model.Descriptor.FormException;
import hudson.tasks.BuildTrigger;
import hudson.tasks.LogRotator;
@@ -116,6 +118,7 @@ public abstract class Job, RunT extends Run, RunT extends Run, RunT extends Run, RunT extends Run, RunT extends Run, RunT extends Run runs = _getRuns();
@@ -398,6 +406,7 @@ public abstract class Job, RunT extends Run runs = _getRuns();
@@ -410,6 +419,7 @@ public abstract class Job, RunT extends Run, RunT extends Run, RunT extends Run, RunT extends Run,RunT extends Run>
extends Actionable implements ExtensionPoint, Comparable {
@@ -158,6 +161,7 @@ public abstract class Run ,RunT extends Run,RunT extends Run,RunT extends Run,RunT extends Run