ignite-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sboi...@apache.org
Subject [41/53] [abbrv] incubator-ignite git commit: # gg-9470-rename
Date Thu, 04 Dec 2014 23:24:33 GMT
# gg-9470-rename


Project: http://git-wip-us.apache.org/repos/asf/incubator-ignite/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ignite/commit/3dcb5222
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ignite/tree/3dcb5222
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ignite/diff/3dcb5222

Branch: refs/heads/master
Commit: 3dcb5222d5ac243e5f347498e80ea14301cb0bc7
Parents: 4e32727
Author: sboikov <sboikov@gridgain.com>
Authored: Thu Dec 4 22:38:26 2014 +0300
Committer: sboikov <sboikov@gridgain.com>
Committed: Thu Dec 4 22:38:26 2014 +0300

----------------------------------------------------------------------
 .../java/org/apache/ignite/IgnitePortables.java | 358 +++++++++++++++++++
 .../grid/cache/store/GridCacheStore.java        |   2 +-
 .../gridgain/grid/kernal/GridPortablesImpl.java |   3 +-
 .../VisorPortableMetadataCollectorTask.java     |   1 +
 .../grid/portables/GridPortableBuilder.java     |   6 +-
 .../grid/portables/GridPortableMetadata.java    |   2 +-
 .../grid/portables/GridPortableObject.java      |   2 +-
 .../grid/portables/IgnitePortables.java         | 357 ------------------
 8 files changed, 367 insertions(+), 364 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/apache/ignite/IgnitePortables.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/IgnitePortables.java b/modules/core/src/main/java/org/apache/ignite/IgnitePortables.java
new file mode 100644
index 0000000..7e8a069
--- /dev/null
+++ b/modules/core/src/main/java/org/apache/ignite/IgnitePortables.java
@@ -0,0 +1,358 @@
+/* @java.file.header */
+
+/*  _________        _____ __________________        _____
+ *  __  ____/___________(_)______  /__  ____/______ ____(_)_______
+ *  _  / __  __  ___/__  / _  __  / _  / __  _  __ `/__  / __  __ \
+ *  / /_/ /  _  /    _  /  / /_/ /  / /_/ /  / /_/ / _  /  _  / / /
+ *  \____/   /_/     /_/   \_,__/   \____/   \__,_/  /_/   /_/ /_/
+ */
+
+package org.apache.ignite;
+
+import org.gridgain.grid.cache.*;
+import org.gridgain.grid.cache.query.*;
+import org.gridgain.grid.portables.*;
+import org.jetbrains.annotations.*;
+
+import java.sql.*;
+import java.util.*;
+import java.util.Date;
+
+/**
+ * Defines portable objects functionality. With portable objects you are able to:
+ * <ul>
+ * <li>Seamlessly interoperate between Java, .NET, and C++.</li>
+ * <li>Make any object portable with zero code change to your existing code.</li>
+ * <li>Nest portable objects within each other.</li>
+ * <li>Automatically handle {@code circular} or {@code null} references.</li>
+ * <li>Automatically convert collections and maps between Java, .NET, and C++.</li>
+ * <li>
+ *      Optionally avoid deserialization of objects on the server side
+ *      (objects are stored in {@link org.gridgain.grid.portables.GridPortableObject} format).
+ * </li>
+ * <li>Avoid need to have concrete class definitions on the server side.</li>
+ * <li>Dynamically change structure of the classes without having to restart the cluster.</li>
+ * <li>Index into portable objects for querying purposes.</li>
+ * </ul>
+ * <h1 class="header">Working With Portables Directly</h1>
+ * Once an object is defined as portable,
+ * GridGain will always store it in memory in the portable (i.e. binary) format.
+ * User can choose to work either with the portable format or with the deserialized form
+ * (assuming that class definitions are present in the classpath).
+ * <p>
+ * To work with the portable format directly, user should create a special cache projection
+ * using {@link GridCacheProjection#keepPortable()} method and then retrieve individual fields
as needed:
+ * <pre name=code class=java>
+ * GridCacheProjection&lt;GridPortableObject.class, GridPortableObject.class&gt;
prj = cache.keepPortable();
+ *
+ * // Convert instance of MyKey to portable format.
+ * // We could also use GridPortableBuilder to create
+ * // the key in portable format directly.
+ * GridPortableObject key = grid.portables().toPortable(new MyKey());
+ *
+ * GridPortableObject val = prj.get(key);
+ *
+ * String field = val.field("myFieldName");
+ * </pre>
+ * Alternatively, if we have class definitions in the classpath, we may choose to work with
deserialized
+ * typed objects at all times. In this case we do incur the deserialization cost, however,
+ * GridGain will only deserialize on the first access and will cache the deserialized object,
+ * so it does not have to be deserialized again:
+ * <pre name=code class=java>
+ * GridCacheProjection&lt;MyKey.class, MyValue.class&gt; prj =
+ *     cache.projection(MyKey.class, MyValue.class);
+ *
+ * MyValue val = prj.get(new MyKey());
+ *
+ * // Normal java getter.
+ * String fieldVal = val.getMyFieldName();
+ * </pre>
+ * If we used, for example, one of the automatically handled portable types for a key, like
integer,
+ * and still wanted to work with binary portable format for values, then we would declare
cache projection
+ * as follows:
+ * <pre name=code class=java>
+ * GridCacheProjection&lt;Integer.class, GridPortableObject.class&gt; prj = cache.keepPortable();
+ * </pre>
+ * <h1 class="header">Automatic Portable Types</h1>
+ * Note that only portable classes are converted to {@link org.gridgain.grid.portables.GridPortableObject}
format. Following
+ * classes are never converted (e.g., {@link #toPortable(Object)} method will return original
+ * object, and instances of these classes will be stored in cache without changes):
+ * <ul>
+ *     <li>All primitives (byte, int, ...) and there boxed versions (Byte, Integer,
...)</li>
+ *     <li>Arrays of primitives (byte[], int[], ...)</li>
+ *     <li>{@link String} and array of {@link String}s</li>
+ *     <li>{@link UUID} and array of {@link UUID}s</li>
+ *     <li>{@link Date} and array of {@link Date}s</li>
+ *     <li>{@link Timestamp} and array of {@link Timestamp}s</li>
+ *     <li>Enums and array of enums</li>
+ *     <li>
+ *         Maps, collections and array of objects (but objects inside
+ *         them will still be converted if they are portable)
+ *     </li>
+ * </ul>
+ * <h1 class="header">Working With Maps and Collections</h1>
+ * All maps and collections in the portable objects are serialized automatically. When working
+ * with different platforms, e.g. C++ or .NET, GridGain will automatically pick the most
+ * adequate collection or map in either language. For example, {@link ArrayList} in Java
will become
+ * {@code List} in C#, {@link LinkedList} in Java is {@link LinkedList} in C#, {@link HashMap}
+ * in Java is {@code Dictionary} in C#, and {@link TreeMap} in Java becomes {@code SortedDictionary}
+ * in C#, etc.
+ * <h1 class="header">Building Portable Objects</h1>
+ * GridGain comes with {@link org.gridgain.grid.portables.GridPortableBuilder} which allows
to build portable objects dynamically:
+ * <pre name=code class=java>
+ * GridPortableBuilder builder = GridGain.grid().portables().builder();
+ *
+ * builder.typeId("MyObject");
+ *
+ * builder.stringField("fieldA", "A");
+ * build.intField("fieldB", "B");
+ *
+ * GridPortableObject portableObj = builder.build();
+ * </pre>
+ * For the cases when class definition is present
+ * in the class path, it is also possible to populate a standard POJO and then
+ * convert it to portable format, like so:
+ * <pre name=code class=java>
+ * MyObject obj = new MyObject();
+ *
+ * obj.setFieldA("A");
+ * obj.setFieldB(123);
+ *
+ * GridPortableObject portableObj = GridGain.grid().portables().toPortable(obj);
+ * </pre>
+ * NOTE: you don't need to convert typed objects to portable format before storing
+ * them in cache, GridGain will do that automatically.
+ * <h1 class="header">Portable Metadata</h1>
+ * Even though GridGain portable protocol only works with hash codes for type and field names
+ * to achieve better performance, GridGain provides metadata for all portable types which
+ * can be queried ar runtime via any of the {@link IgnitePortables#metadata(Class) GridPortables.metadata(...)}
+ * methods. Having metadata also allows for proper formatting of {@code GridPortableObject.toString()}
method,
+ * even when portable objects are kept in binary format only, which may be necessary for
audit reasons.
+ * <h1 class="header">Dynamic Structure Changes</h1>
+ * Since objects are always cached in the portable binary format, server does not need to
+ * be aware of the class definitions. Moreover, if class definitions are not present or not
+ * used on the server, then clients can continuously change the structure of the portable
+ * objects without having to restart the cluster. For example, if one client stores a
+ * certain class with fields A and B, and another client stores the same class with
+ * fields B and C, then the server-side portable object will have the fields A, B, and C.
+ * As the structure of a portable object changes, the new fields become available for SQL
queries
+ * automatically.
+ * <h1 class="header">Configuration</h1>
+ * To make any object portable, you have to specify it in {@link org.gridgain.grid.portables.GridPortableConfiguration}
+ * at startup. The only requirement GridGain imposes is that your object has an empty
+ * constructor. Note, that since server side does not have to know the class definition,
+ * you only need to list portable objects in configuration on the client side. However, if
you
+ * list them on the server side as well, then you get the ability to deserialize portable
objects
+ * into concrete types on the server as well as on the client.
+ * <p>
+ * Here is an example of portable configuration (note that star (*) notation is supported):
+ * <pre name=code class=xml>
+ * ...
+ * &lt;!-- Portable objects configuration. --&gt;
+ * &lt;property name="portableConfiguration"&gt;
+ *     &lt;bean class="org.gridgain.grid.portables.GridPortableConfiguration"&gt;
+ *         &lt;property name="classNames"&gt;
+ *             &lt;list&gt;
+ *                 &lt;value&gt;my.package.for.portable.objects.*&lt;/value&gt;
+ *                 &lt;value&gt;org.gridgain.examples.client.portable.Employee&lt;/value&gt;
+ *             &lt;/list&gt;
+ *         &lt;/property&gt;
+ *     &lt;/bean&gt;
+ * &lt;/property&gt;
+ * ...
+ * </pre>
+ * or from code:
+ * <pre name=code class=java>
+ * GridConfiguration gridCfg = new GridConfiguration();
+ *
+ * GridPortableConfiguration portCfg = new GridPortableConfiguration();
+ *
+ * portCfg.setClassNames(Arrays.asList(
+ *     Employee.class.getName(),
+ *     Address.class.getName())
+ * );
+ *
+ * gridCfg.setPortableConfiguration(portCfg);
+ * </pre>
+ * You can also specify class name for a portable object via {@link org.gridgain.grid.portables.GridPortableTypeConfiguration}.
+ * Do it in case if you need to override other configuration properties on per-type level,
like
+ * ID-mapper, or serializer.
+ * <h1 class="header">Custom Affinity Keys</h1>
+ * Often you need to specify an alternate key (not the cache key) for affinity routing whenever
+ * storing objects in cache. For example, if you are caching {@code Employee} object with
+ * {@code Organization}, and want to colocate employees with organization they work for,
+ * so you can process them together, you need to specify an alternate affinity key.
+ * With portable objects you would have to do it as following:
+ * <pre name=code class=xml>
+ * &lt;property name="portableConfiguration"&gt;
+ *     &lt;bean class="org.gridgain.grid.portables.GridPortableConfiguration"&gt;
+ *         ...
+ *         &lt;property name="typeConfigurations"&gt;
+ *             &lt;list&gt;
+ *                 &lt;bean class="org.gridgain.grid.portables.GridPortableTypeConfiguration"&gt;
+ *                     &lt;property name="className" value="org.gridgain.examples.client.portable.EmployeeKey"/&gt;
+ *                     &lt;property name="affinityKeyFieldName" value="organizationId"/&gt;
+ *                 &lt;/bean&gt;
+ *             &lt;/list&gt;
+ *         &lt;/property&gt;
+ *         ...
+ *     &lt;/bean&gt;
+ * &lt;/property&gt;
+ * </pre>
+ * <h1 class="header">Serialization</h1>
+ * Once portable object is specified in {@link org.gridgain.grid.portables.GridPortableConfiguration},
GridGain will
+ * be able to serialize and deserialize it. However, you can provide your own custom
+ * serialization logic by optionally implementing {@link org.gridgain.grid.portables.GridPortableMarshalAware}
interface, like so:
+ * <pre name=code class=java>
+ * public class Address implements GridPortableMarshalAware {
+ *     private String street;
+ *     private int zip;
+ *
+ *     // Empty constructor required for portable deserialization.
+ *     public Address() {}
+ *
+ *     &#64;Override public void writePortable(GridPortableWriter writer) throws GridPortableException
{
+ *         writer.writeString("street", street);
+ *         writer.writeInt("zip", zip);
+ *     }
+ *
+ *     &#64;Override public void readPortable(GridPortableReader reader) throws GridPortableException
{
+ *         street = reader.readString("street");
+ *         zip = reader.readInt("zip");
+ *     }
+ * }
+ * </pre>
+ * Alternatively, if you cannot change class definitions, you can provide custom serialization
+ * logic in {@link org.gridgain.grid.portables.GridPortableSerializer} either globally in
{@link org.gridgain.grid.portables.GridPortableConfiguration} or
+ * for a specific type via {@link org.gridgain.grid.portables.GridPortableTypeConfiguration}
instance.
+ * <p>
+ * Similar to java serialization you can use {@code writeReplace()} and {@code readResolve()}
methods.
+ * <ul>
+ *     <li>
+ *         {@code readResolve} is defined as follows: {@code ANY-ACCESS-MODIFIER Object readResolve()}.
+ *         It may be used to replace the de-serialized object by another one of your choice.
+ *     </li>
+ *     <li>
+ *          {@code writeReplace} is defined as follows: {@code ANY-ACCESS-MODIFIER Object
writeReplace()}. This method allows the
+ *          developer to provide a replacement object that will be serialized instead of
the original one.
+ *     </li>
+ * </ul>
+ *
+ * <h1 class="header">Custom ID Mappers</h1>
+ * GridGain implementation uses name hash codes to generate IDs for class names or field
names
+ * internally. However, in cases when you want to provide your own ID mapping schema,
+ * you can provide your own {@link org.gridgain.grid.portables.GridPortableIdMapper} implementation.
+ * <p>
+ * ID-mapper may be provided either globally in {@link org.gridgain.grid.portables.GridPortableConfiguration},
+ * or for a specific type via {@link org.gridgain.grid.portables.GridPortableTypeConfiguration}
instance.
+ * <h1 class="header">Query Indexing</h1>
+ * Portable objects can be indexed for querying by specifying index fields in
+ * {@link GridCacheQueryTypeMetadata} inside of specific {@link GridCacheConfiguration} instance,
+ * like so:
+ * <pre name=code class=xml>
+ * ...
+ * &lt;bean class="org.gridgain.grid.cache.GridCacheConfiguration"&gt;
+ *     ...
+ *     &lt;property name="queryConfiguration"&gt;
+ *         &lt;bean class="org.gridgain.grid.cache.query.GridCacheQueryConfiguration"&gt;
+ *             &lt;property name="typeMetadata"&gt;
+ *                 &lt;list&gt;
+ *                     &lt;bean class="org.gridgain.grid.cache.query.GridCacheQueryTypeMetadata"&gt;
+ *                         &lt;property name="type" value="Employee"/&gt;
+ *
+ *                         &lt;!-- Fields to index in ascending order. --&gt;
+ *                         &lt;property name="ascendingFields"&gt;
+ *                             &lt;map&gt;
+ *                             	&lt;entry key="name" value="java.lang.String"/&gt;
+ *
+ *                                 &lt;!-- Nested portable objects can also be indexed.
--&gt;
+ *                                 &lt;entry key="address.zip" value="java.lang.Integer"/&gt;
+ *                             &lt;/map&gt;
+ *                         &lt;/property&gt;
+ *                     &lt;/bean&gt;
+ *                 &lt;/list&gt;
+ *             &lt;/property&gt;
+ *         &lt;/bean&gt;
+ *     &lt;/property&gt;
+ * &lt;/bean&gt;
+ * </pre>
+ */
+public interface IgnitePortables {
+    /**
+     * Gets type ID for given type name.
+     *
+     * @param typeName Type name.
+     * @return Type ID.
+     */
+    public int typeId(String typeName);
+
+    /**
+     * Converts provided object to instance of {@link org.gridgain.grid.portables.GridPortableObject}.
+     * <p>
+     * Note that object's type needs to be configured in {@link org.gridgain.grid.portables.GridPortableConfiguration}.
+     *
+     * @param obj Object to convert.
+     * @return Converted object.
+     * @throws org.gridgain.grid.portables.GridPortableException In case of error.
+     */
+    public <T> T toPortable(@Nullable Object obj) throws GridPortableException;
+
+    /**
+     * Creates new portable builder.
+     *
+     * @param typeId ID of the type.
+     * @return Newly portable builder.
+     */
+    public GridPortableBuilder builder(int typeId);
+
+    /**
+     * Creates new portable builder.
+     *
+     * @param typeName Type name.
+     * @return Newly portable builder.
+     */
+    public GridPortableBuilder builder(String typeName);
+
+    /**
+     * Creates portable builder initialized by existing portable object.
+     *
+     * @param portableObj Portable object to initialize builder.
+     * @return Portable builder.
+     */
+    public GridPortableBuilder builder(GridPortableObject portableObj);
+
+    /**
+     * Gets metadata for provided class.
+     *
+     * @param cls Class.
+     * @return Metadata.
+     * @throws GridPortableException In case of error.
+     */
+    @Nullable public GridPortableMetadata metadata(Class<?> cls) throws GridPortableException;
+
+    /**
+     * Gets metadata for provided class name.
+     *
+     * @param typeName Type name.
+     * @return Metadata.
+     * @throws GridPortableException In case of error.
+     */
+    @Nullable public GridPortableMetadata metadata(String typeName) throws GridPortableException;
+
+    /**
+     * Gets metadata for provided type ID.
+     *
+     * @param typeId Type ID.
+     * @return Metadata.
+     * @throws GridPortableException In case of error.
+     */
+    @Nullable public GridPortableMetadata metadata(int typeId) throws GridPortableException;
+
+    /**
+     * Gets metadata for all known types.
+     *
+     * @return Metadata.
+     * @throws GridPortableException In case of error.
+     */
+    public Collection<GridPortableMetadata> metadata() throws GridPortableException;
+}

http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/gridgain/grid/cache/store/GridCacheStore.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/gridgain/grid/cache/store/GridCacheStore.java
b/modules/core/src/main/java/org/gridgain/grid/cache/store/GridCacheStore.java
index c257015..e054e18 100644
--- a/modules/core/src/main/java/org/gridgain/grid/cache/store/GridCacheStore.java
+++ b/modules/core/src/main/java/org/gridgain/grid/cache/store/GridCacheStore.java
@@ -88,7 +88,7 @@ import java.util.Date;
  *     </li>
  * </ul>
  *
- * @see org.gridgain.grid.portables.IgnitePortables
+ * @see org.apache.ignite.IgnitePortables
  */
 public interface GridCacheStore<K, V> {
     /**

http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/gridgain/grid/kernal/GridPortablesImpl.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/gridgain/grid/kernal/GridPortablesImpl.java b/modules/core/src/main/java/org/gridgain/grid/kernal/GridPortablesImpl.java
index 29f36dd..146cf62 100644
--- a/modules/core/src/main/java/org/gridgain/grid/kernal/GridPortablesImpl.java
+++ b/modules/core/src/main/java/org/gridgain/grid/kernal/GridPortablesImpl.java
@@ -9,6 +9,7 @@
 
 package org.gridgain.grid.kernal;
 
+import org.apache.ignite.*;
 import org.gridgain.grid.kernal.processors.portable.*;
 import org.gridgain.grid.portables.*;
 import org.jetbrains.annotations.*;
@@ -16,7 +17,7 @@ import org.jetbrains.annotations.*;
 import java.util.*;
 
 /**
- * {@link org.gridgain.grid.portables.IgnitePortables} implementation.
+ * {@link org.apache.ignite.IgnitePortables} implementation.
  */
 public class GridPortablesImpl implements IgnitePortables {
     /** */

http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/gridgain/grid/kernal/visor/portable/VisorPortableMetadataCollectorTask.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/gridgain/grid/kernal/visor/portable/VisorPortableMetadataCollectorTask.java
b/modules/core/src/main/java/org/gridgain/grid/kernal/visor/portable/VisorPortableMetadataCollectorTask.java
index 76744b0..938c8e5 100644
--- a/modules/core/src/main/java/org/gridgain/grid/kernal/visor/portable/VisorPortableMetadataCollectorTask.java
+++ b/modules/core/src/main/java/org/gridgain/grid/kernal/visor/portable/VisorPortableMetadataCollectorTask.java
@@ -9,6 +9,7 @@
 
 package org.gridgain.grid.kernal.visor.portable;
 
+import org.apache.ignite.*;
 import org.apache.ignite.lang.*;
 import org.gridgain.grid.*;
 import org.gridgain.grid.kernal.processors.task.*;

http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableBuilder.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableBuilder.java
b/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableBuilder.java
index 4201fd3..813acf8 100644
--- a/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableBuilder.java
+++ b/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableBuilder.java
@@ -53,9 +53,9 @@ import org.jetbrains.annotations.*;
  * String city = personPortableObj.getField("address").getField("city");
  * </pre>
  *
- * @see IgnitePortables#builder(int)
- * @see IgnitePortables#builder(String)
- * @see IgnitePortables#builder(GridPortableObject)
+ * @see org.apache.ignite.IgnitePortables#builder(int)
+ * @see org.apache.ignite.IgnitePortables#builder(String)
+ * @see org.apache.ignite.IgnitePortables#builder(GridPortableObject)
  */
 public interface GridPortableBuilder {
     /**

http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableMetadata.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableMetadata.java
b/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableMetadata.java
index f7103c9..59dff2b 100644
--- a/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableMetadata.java
+++ b/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableMetadata.java
@@ -15,7 +15,7 @@ import java.util.*;
 
 /**
  * Portable type meta data. Metadata for portable types can be accessed from any of the
- * {@link IgnitePortables#metadata(String) GridPortables.metadata(...)} methods.
+ * {@link org.apache.ignite.IgnitePortables#metadata(String) GridPortables.metadata(...)}
methods.
  * Having metadata also allows for proper formatting of {@code GridPortableObject.toString()}
method,
  * even when portable objects are kept in binary format only, which may be necessary for
audit reasons.
  */

http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableObject.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableObject.java
b/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableObject.java
index c201e7b..952c5c8 100644
--- a/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableObject.java
+++ b/modules/core/src/main/java/org/gridgain/grid/portables/GridPortableObject.java
@@ -105,7 +105,7 @@ import java.util.*;
  * <h1 class="header">Portable Metadata</h1>
  * Even though GridGain portable protocol only works with hash codes for type and field names
  * to achieve better performance, GridGain provides metadata for all portable types which
- * can be queried ar runtime via any of the {@link IgnitePortables#metadata(Class) GridPortables.metadata(...)}
+ * can be queried ar runtime via any of the {@link org.apache.ignite.IgnitePortables#metadata(Class)
GridPortables.metadata(...)}
  * methods. Having metadata also allows for proper formatting of {@code GridPortableObject.toString()}
method,
  * even when portable objects are kept in binary format only, which may be necessary for
audit reasons.
  */

http://git-wip-us.apache.org/repos/asf/incubator-ignite/blob/3dcb5222/modules/core/src/main/java/org/gridgain/grid/portables/IgnitePortables.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/gridgain/grid/portables/IgnitePortables.java b/modules/core/src/main/java/org/gridgain/grid/portables/IgnitePortables.java
deleted file mode 100644
index 6471551..0000000
--- a/modules/core/src/main/java/org/gridgain/grid/portables/IgnitePortables.java
+++ /dev/null
@@ -1,357 +0,0 @@
-/* @java.file.header */
-
-/*  _________        _____ __________________        _____
- *  __  ____/___________(_)______  /__  ____/______ ____(_)_______
- *  _  / __  __  ___/__  / _  __  / _  / __  _  __ `/__  / __  __ \
- *  / /_/ /  _  /    _  /  / /_/ /  / /_/ /  / /_/ / _  /  _  / / /
- *  \____/   /_/     /_/   \_,__/   \____/   \__,_/  /_/   /_/ /_/
- */
-
-package org.gridgain.grid.portables;
-
-import org.gridgain.grid.cache.*;
-import org.gridgain.grid.cache.query.*;
-import org.jetbrains.annotations.*;
-
-import java.sql.*;
-import java.util.*;
-import java.util.Date;
-
-/**
- * Defines portable objects functionality. With portable objects you are able to:
- * <ul>
- * <li>Seamlessly interoperate between Java, .NET, and C++.</li>
- * <li>Make any object portable with zero code change to your existing code.</li>
- * <li>Nest portable objects within each other.</li>
- * <li>Automatically handle {@code circular} or {@code null} references.</li>
- * <li>Automatically convert collections and maps between Java, .NET, and C++.</li>
- * <li>
- *      Optionally avoid deserialization of objects on the server side
- *      (objects are stored in {@link GridPortableObject} format).
- * </li>
- * <li>Avoid need to have concrete class definitions on the server side.</li>
- * <li>Dynamically change structure of the classes without having to restart the cluster.</li>
- * <li>Index into portable objects for querying purposes.</li>
- * </ul>
- * <h1 class="header">Working With Portables Directly</h1>
- * Once an object is defined as portable,
- * GridGain will always store it in memory in the portable (i.e. binary) format.
- * User can choose to work either with the portable format or with the deserialized form
- * (assuming that class definitions are present in the classpath).
- * <p>
- * To work with the portable format directly, user should create a special cache projection
- * using {@link GridCacheProjection#keepPortable()} method and then retrieve individual fields
as needed:
- * <pre name=code class=java>
- * GridCacheProjection&lt;GridPortableObject.class, GridPortableObject.class&gt;
prj = cache.keepPortable();
- *
- * // Convert instance of MyKey to portable format.
- * // We could also use GridPortableBuilder to create
- * // the key in portable format directly.
- * GridPortableObject key = grid.portables().toPortable(new MyKey());
- *
- * GridPortableObject val = prj.get(key);
- *
- * String field = val.field("myFieldName");
- * </pre>
- * Alternatively, if we have class definitions in the classpath, we may choose to work with
deserialized
- * typed objects at all times. In this case we do incur the deserialization cost, however,
- * GridGain will only deserialize on the first access and will cache the deserialized object,
- * so it does not have to be deserialized again:
- * <pre name=code class=java>
- * GridCacheProjection&lt;MyKey.class, MyValue.class&gt; prj =
- *     cache.projection(MyKey.class, MyValue.class);
- *
- * MyValue val = prj.get(new MyKey());
- *
- * // Normal java getter.
- * String fieldVal = val.getMyFieldName();
- * </pre>
- * If we used, for example, one of the automatically handled portable types for a key, like
integer,
- * and still wanted to work with binary portable format for values, then we would declare
cache projection
- * as follows:
- * <pre name=code class=java>
- * GridCacheProjection&lt;Integer.class, GridPortableObject.class&gt; prj = cache.keepPortable();
- * </pre>
- * <h1 class="header">Automatic Portable Types</h1>
- * Note that only portable classes are converted to {@link GridPortableObject} format. Following
- * classes are never converted (e.g., {@link #toPortable(Object)} method will return original
- * object, and instances of these classes will be stored in cache without changes):
- * <ul>
- *     <li>All primitives (byte, int, ...) and there boxed versions (Byte, Integer,
...)</li>
- *     <li>Arrays of primitives (byte[], int[], ...)</li>
- *     <li>{@link String} and array of {@link String}s</li>
- *     <li>{@link UUID} and array of {@link UUID}s</li>
- *     <li>{@link Date} and array of {@link Date}s</li>
- *     <li>{@link Timestamp} and array of {@link Timestamp}s</li>
- *     <li>Enums and array of enums</li>
- *     <li>
- *         Maps, collections and array of objects (but objects inside
- *         them will still be converted if they are portable)
- *     </li>
- * </ul>
- * <h1 class="header">Working With Maps and Collections</h1>
- * All maps and collections in the portable objects are serialized automatically. When working
- * with different platforms, e.g. C++ or .NET, GridGain will automatically pick the most
- * adequate collection or map in either language. For example, {@link ArrayList} in Java
will become
- * {@code List} in C#, {@link LinkedList} in Java is {@link LinkedList} in C#, {@link HashMap}
- * in Java is {@code Dictionary} in C#, and {@link TreeMap} in Java becomes {@code SortedDictionary}
- * in C#, etc.
- * <h1 class="header">Building Portable Objects</h1>
- * GridGain comes with {@link GridPortableBuilder} which allows to build portable objects
dynamically:
- * <pre name=code class=java>
- * GridPortableBuilder builder = GridGain.grid().portables().builder();
- *
- * builder.typeId("MyObject");
- *
- * builder.stringField("fieldA", "A");
- * build.intField("fieldB", "B");
- *
- * GridPortableObject portableObj = builder.build();
- * </pre>
- * For the cases when class definition is present
- * in the class path, it is also possible to populate a standard POJO and then
- * convert it to portable format, like so:
- * <pre name=code class=java>
- * MyObject obj = new MyObject();
- *
- * obj.setFieldA("A");
- * obj.setFieldB(123);
- *
- * GridPortableObject portableObj = GridGain.grid().portables().toPortable(obj);
- * </pre>
- * NOTE: you don't need to convert typed objects to portable format before storing
- * them in cache, GridGain will do that automatically.
- * <h1 class="header">Portable Metadata</h1>
- * Even though GridGain portable protocol only works with hash codes for type and field names
- * to achieve better performance, GridGain provides metadata for all portable types which
- * can be queried ar runtime via any of the {@link IgnitePortables#metadata(Class) GridPortables.metadata(...)}
- * methods. Having metadata also allows for proper formatting of {@code GridPortableObject.toString()}
method,
- * even when portable objects are kept in binary format only, which may be necessary for
audit reasons.
- * <h1 class="header">Dynamic Structure Changes</h1>
- * Since objects are always cached in the portable binary format, server does not need to
- * be aware of the class definitions. Moreover, if class definitions are not present or not
- * used on the server, then clients can continuously change the structure of the portable
- * objects without having to restart the cluster. For example, if one client stores a
- * certain class with fields A and B, and another client stores the same class with
- * fields B and C, then the server-side portable object will have the fields A, B, and C.
- * As the structure of a portable object changes, the new fields become available for SQL
queries
- * automatically.
- * <h1 class="header">Configuration</h1>
- * To make any object portable, you have to specify it in {@link GridPortableConfiguration}
- * at startup. The only requirement GridGain imposes is that your object has an empty
- * constructor. Note, that since server side does not have to know the class definition,
- * you only need to list portable objects in configuration on the client side. However, if
you
- * list them on the server side as well, then you get the ability to deserialize portable
objects
- * into concrete types on the server as well as on the client.
- * <p>
- * Here is an example of portable configuration (note that star (*) notation is supported):
- * <pre name=code class=xml>
- * ...
- * &lt;!-- Portable objects configuration. --&gt;
- * &lt;property name="portableConfiguration"&gt;
- *     &lt;bean class="org.gridgain.grid.portables.GridPortableConfiguration"&gt;
- *         &lt;property name="classNames"&gt;
- *             &lt;list&gt;
- *                 &lt;value&gt;my.package.for.portable.objects.*&lt;/value&gt;
- *                 &lt;value&gt;org.gridgain.examples.client.portable.Employee&lt;/value&gt;
- *             &lt;/list&gt;
- *         &lt;/property&gt;
- *     &lt;/bean&gt;
- * &lt;/property&gt;
- * ...
- * </pre>
- * or from code:
- * <pre name=code class=java>
- * GridConfiguration gridCfg = new GridConfiguration();
- *
- * GridPortableConfiguration portCfg = new GridPortableConfiguration();
- *
- * portCfg.setClassNames(Arrays.asList(
- *     Employee.class.getName(),
- *     Address.class.getName())
- * );
- *
- * gridCfg.setPortableConfiguration(portCfg);
- * </pre>
- * You can also specify class name for a portable object via {@link GridPortableTypeConfiguration}.
- * Do it in case if you need to override other configuration properties on per-type level,
like
- * ID-mapper, or serializer.
- * <h1 class="header">Custom Affinity Keys</h1>
- * Often you need to specify an alternate key (not the cache key) for affinity routing whenever
- * storing objects in cache. For example, if you are caching {@code Employee} object with
- * {@code Organization}, and want to colocate employees with organization they work for,
- * so you can process them together, you need to specify an alternate affinity key.
- * With portable objects you would have to do it as following:
- * <pre name=code class=xml>
- * &lt;property name="portableConfiguration"&gt;
- *     &lt;bean class="org.gridgain.grid.portables.GridPortableConfiguration"&gt;
- *         ...
- *         &lt;property name="typeConfigurations"&gt;
- *             &lt;list&gt;
- *                 &lt;bean class="org.gridgain.grid.portables.GridPortableTypeConfiguration"&gt;
- *                     &lt;property name="className" value="org.gridgain.examples.client.portable.EmployeeKey"/&gt;
- *                     &lt;property name="affinityKeyFieldName" value="organizationId"/&gt;
- *                 &lt;/bean&gt;
- *             &lt;/list&gt;
- *         &lt;/property&gt;
- *         ...
- *     &lt;/bean&gt;
- * &lt;/property&gt;
- * </pre>
- * <h1 class="header">Serialization</h1>
- * Once portable object is specified in {@link GridPortableConfiguration}, GridGain will
- * be able to serialize and deserialize it. However, you can provide your own custom
- * serialization logic by optionally implementing {@link GridPortableMarshalAware} interface,
like so:
- * <pre name=code class=java>
- * public class Address implements GridPortableMarshalAware {
- *     private String street;
- *     private int zip;
- *
- *     // Empty constructor required for portable deserialization.
- *     public Address() {}
- *
- *     &#64;Override public void writePortable(GridPortableWriter writer) throws GridPortableException
{
- *         writer.writeString("street", street);
- *         writer.writeInt("zip", zip);
- *     }
- *
- *     &#64;Override public void readPortable(GridPortableReader reader) throws GridPortableException
{
- *         street = reader.readString("street");
- *         zip = reader.readInt("zip");
- *     }
- * }
- * </pre>
- * Alternatively, if you cannot change class definitions, you can provide custom serialization
- * logic in {@link GridPortableSerializer} either globally in {@link GridPortableConfiguration}
or
- * for a specific type via {@link GridPortableTypeConfiguration} instance.
- * <p>
- * Similar to java serialization you can use {@code writeReplace()} and {@code readResolve()}
methods.
- * <ul>
- *     <li>
- *         {@code readResolve} is defined as follows: {@code ANY-ACCESS-MODIFIER Object readResolve()}.
- *         It may be used to replace the de-serialized object by another one of your choice.
- *     </li>
- *     <li>
- *          {@code writeReplace} is defined as follows: {@code ANY-ACCESS-MODIFIER Object
writeReplace()}. This method allows the
- *          developer to provide a replacement object that will be serialized instead of
the original one.
- *     </li>
- * </ul>
- *
- * <h1 class="header">Custom ID Mappers</h1>
- * GridGain implementation uses name hash codes to generate IDs for class names or field
names
- * internally. However, in cases when you want to provide your own ID mapping schema,
- * you can provide your own {@link GridPortableIdMapper} implementation.
- * <p>
- * ID-mapper may be provided either globally in {@link GridPortableConfiguration},
- * or for a specific type via {@link GridPortableTypeConfiguration} instance.
- * <h1 class="header">Query Indexing</h1>
- * Portable objects can be indexed for querying by specifying index fields in
- * {@link GridCacheQueryTypeMetadata} inside of specific {@link GridCacheConfiguration} instance,
- * like so:
- * <pre name=code class=xml>
- * ...
- * &lt;bean class="org.gridgain.grid.cache.GridCacheConfiguration"&gt;
- *     ...
- *     &lt;property name="queryConfiguration"&gt;
- *         &lt;bean class="org.gridgain.grid.cache.query.GridCacheQueryConfiguration"&gt;
- *             &lt;property name="typeMetadata"&gt;
- *                 &lt;list&gt;
- *                     &lt;bean class="org.gridgain.grid.cache.query.GridCacheQueryTypeMetadata"&gt;
- *                         &lt;property name="type" value="Employee"/&gt;
- *
- *                         &lt;!-- Fields to index in ascending order. --&gt;
- *                         &lt;property name="ascendingFields"&gt;
- *                             &lt;map&gt;
- *                             	&lt;entry key="name" value="java.lang.String"/&gt;
- *
- *                                 &lt;!-- Nested portable objects can also be indexed.
--&gt;
- *                                 &lt;entry key="address.zip" value="java.lang.Integer"/&gt;
- *                             &lt;/map&gt;
- *                         &lt;/property&gt;
- *                     &lt;/bean&gt;
- *                 &lt;/list&gt;
- *             &lt;/property&gt;
- *         &lt;/bean&gt;
- *     &lt;/property&gt;
- * &lt;/bean&gt;
- * </pre>
- */
-public interface IgnitePortables {
-    /**
-     * Gets type ID for given type name.
-     *
-     * @param typeName Type name.
-     * @return Type ID.
-     */
-    public int typeId(String typeName);
-
-    /**
-     * Converts provided object to instance of {@link GridPortableObject}.
-     * <p>
-     * Note that object's type needs to be configured in {@link GridPortableConfiguration}.
-     *
-     * @param obj Object to convert.
-     * @return Converted object.
-     * @throws GridPortableException In case of error.
-     */
-    public <T> T toPortable(@Nullable Object obj) throws GridPortableException;
-
-    /**
-     * Creates new portable builder.
-     *
-     * @param typeId ID of the type.
-     * @return Newly portable builder.
-     */
-    public GridPortableBuilder builder(int typeId);
-
-    /**
-     * Creates new portable builder.
-     *
-     * @param typeName Type name.
-     * @return Newly portable builder.
-     */
-    public GridPortableBuilder builder(String typeName);
-
-    /**
-     * Creates portable builder initialized by existing portable object.
-     *
-     * @param portableObj Portable object to initialize builder.
-     * @return Portable builder.
-     */
-    public GridPortableBuilder builder(GridPortableObject portableObj);
-
-    /**
-     * Gets metadata for provided class.
-     *
-     * @param cls Class.
-     * @return Metadata.
-     * @throws GridPortableException In case of error.
-     */
-    @Nullable public GridPortableMetadata metadata(Class<?> cls) throws GridPortableException;
-
-    /**
-     * Gets metadata for provided class name.
-     *
-     * @param typeName Type name.
-     * @return Metadata.
-     * @throws GridPortableException In case of error.
-     */
-    @Nullable public GridPortableMetadata metadata(String typeName) throws GridPortableException;
-
-    /**
-     * Gets metadata for provided type ID.
-     *
-     * @param typeId Type ID.
-     * @return Metadata.
-     * @throws GridPortableException In case of error.
-     */
-    @Nullable public GridPortableMetadata metadata(int typeId) throws GridPortableException;
-
-    /**
-     * Gets metadata for all known types.
-     *
-     * @return Metadata.
-     * @throws GridPortableException In case of error.
-     */
-    public Collection<GridPortableMetadata> metadata() throws GridPortableException;
-}


Mime
View raw message