Johannes
/
gson-comments
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
gson-comments/gson/docs/javadocs/com/google/gson/InstanceCreator.html

276 lines
12 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.6.0_01) on Fri Aug 29 15:11:27 PDT 2008 -->
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>
InstanceCreator (Gson 1.2 API)
</TITLE>
<META NAME="date" CONTENT="2008-08-29">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="InstanceCreator (Gson 1.2 API)";
}
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<HR>
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/InstanceCreator.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../com/google/gson/GsonBuilder.html" title="class in com.google.gson"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../com/google/gson/JsonArray.html" title="class in com.google.gson"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../index.html?com/google/gson/InstanceCreator.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="InstanceCreator.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
com.google.gson</FONT>
<BR>
Interface InstanceCreator&lt;T&gt;</H2>
<DL>
<DT><DT><B>Type Parameters:</B><DD><CODE>T</CODE> - the type of object that will be created by this implementation.</DL>
<HR>
<DL>
<DT><PRE>public interface <B>InstanceCreator&lt;T&gt;</B></DL>
</PRE>
<P>
This interface is implemented to create instances of a class that does not define a no-args
constructor. If you can modify the class, you should instead add a private, or public
no-args constructor. However, that is not possible for library classes, such as JDK classes, or
a third-party library that you do not have source-code of. In such cases, you should define an
instance creator for the class. Implementations of this interface should be registered with
<A HREF="../../../com/google/gson/GsonBuilder.html#registerTypeAdapter(java.lang.reflect.Type, java.lang.Object)"><CODE>GsonBuilder.registerTypeAdapter(Type, Object)</CODE></A> method before Gson will be able to use
them.
<p>Let us look at an example where defining an InstanceCreator might be useful. The
<code>Id</code> class defined below does not have a default no-args constructor.</p>
<pre>
public class Id&lt;T&gt; {
private final Class&lt;T&gt; clazz;
private final long value;
public Id(Class&lt;T&gt; clazz, long value) {
this.clazz = clazz;
this.value = value;
}
}
</pre>
<p>If Gson encounters an object of type <code>Id</code> during deserialization, it will throw an
exception. The easiest way to solve this problem will be to add a (public or private) no-args
constructor as follows:</p>
<pre>
private Id() {
this(Object.class, 0L);
}
</pre>
<p>However, let us assume that the developer does not have access to the source-code of the
<code>Id</code> class, or does not want to define a no-args constructor for it. The developer
can solve this problem by defining an <code>InstanceCreator</code> for <code>Id</code>:</p>
<pre>
class IdInstanceCreator implements InstanceCreator&lt;Id&gt; {
public Id createInstance(Type type) {
return new Id(Object.class, 0L);
}
}
</pre>
<p>Note that it does not matter what the fields of the created instance contain since Gson will
overwrite them with the deserialized values specified in Json. You should also ensure that a
<i>new</i> object is returned, not a common object since its fields will be overwritten.
The developer will need to register <code>IdInstanceCreator</code> with Gson as follows:</p>
<pre>
Gson gson = new GsonBuilder().registerTypeAdapter(Id.class, new IdInstanceCreator()).create();
</pre>
<P>
<P>
<DL>
<DT><B>Author:</B></DT>
<DD>Joel Leitch</DD>
</DL>
<HR>
<P>
<!-- ========== METHOD SUMMARY =========== -->
<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Method Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;<A HREF="../../../com/google/gson/InstanceCreator.html" title="type parameter in InstanceCreator">T</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../com/google/gson/InstanceCreator.html#createInstance(java.lang.reflect.Type)">createInstance</A></B>(<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/reflect/Type.html?is-external=true" title="class or interface in java.lang.reflect">Type</A>&nbsp;type)</CODE>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Gson invokes this call-back method during deserialization to create an instance of the
specified type.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<!-- ============ METHOD DETAIL ========== -->
<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
<B>Method Detail</B></FONT></TH>
</TR>
</TABLE>
<A NAME="createInstance(java.lang.reflect.Type)"><!-- --></A><H3>
createInstance</H3>
<PRE>
<A HREF="../../../com/google/gson/InstanceCreator.html" title="type parameter in InstanceCreator">T</A> <B>createInstance</B>(<A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/reflect/Type.html?is-external=true" title="class or interface in java.lang.reflect">Type</A>&nbsp;type)</PRE>
<DL>
<DD>Gson invokes this call-back method during deserialization to create an instance of the
specified type. The fields of the returned instance are overwritten with the data present
in the Json. Since the prior contents of the object are destroyed and overwritten, do not
return an instance that is useful elsewhere. In particular, do not return a common instance,
always use <code>new</code> to create a new instance.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>type</CODE> - the parameterized T represented as a <A HREF="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/reflect/Type.html?is-external=true" title="class or interface in java.lang.reflect"><CODE>Type</CODE></A>.
<DT><B>Returns:</B><DD>a default object instance of type T.</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/InstanceCreator.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../com/google/gson/GsonBuilder.html" title="class in com.google.gson"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../com/google/gson/JsonArray.html" title="class in com.google.gson"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../index.html?com/google/gson/InstanceCreator.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="InstanceCreator.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
Copyright &#169; 2008. All Rights Reserved.
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink