Feature/custom implementation of interfaces (#3060)

* started on documentation on how to extend or implement custom NEST types for serialization purposes

* Renamed RenameAttribute to PropertyNameAttribute, added tests that custom IProperty implementations serialize to fix #3049

* updated tests and documentation

Author: Mpdreamz

docs/client-concepts/certificates/working-with-certificates.asciidoc

@@ -81,8 +81,7 @@ If your client application has access to the public CA certificate locally, Elas
 that can assert that a certificate the server presents is one that came from the local CA.
 
 If you use X-Pack's {ref_current}/certutil.html[+certutil+ tool] to generate SSL certificates, the generated node certificate
-does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use
-`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
+does not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
 the certificate the server presented was generated using it
 
 [source,csharp]
@@ -151,8 +150,11 @@ public class PkiCluster : CertgenCaCluster
 }
 ----
 <1> Set the client certificate on `ConnectionSettings`
+
 <2> The path to the `.cer` file
+
 <3> The path to the `.key` file
+
 <4> The password for the private key
 
 Or per request on `RequestConfiguration` which will take precedence over the ones defined on `ConnectionConfiguration`

docs/client-concepts/high-level/inference/field-inference.asciidoc

@@ -346,7 +346,7 @@ the `JsonPropertyAttribute` into account
 ----
 public class SerializerSpecific
 {
-    [Rename("nameInJson"), JsonProperty("nameInJson")]
+    [PropertyName("nameInJson"), JsonProperty("nameInJson")]
     public string Name { get; set; }
 }
 
@@ -361,7 +361,7 @@ If both a NEST property attribute and a serializer specific attribute are presen
 public class Both
 {
     [Text(Name = "naam")]
-    [Rename("nameInJson"), JsonProperty("nameInJson")]
+    [PropertyName("nameInJson"), JsonProperty("nameInJson")]
     public string Name { get; set; }
 }
 
@@ -455,31 +455,31 @@ The following example class will demonstrate this precedence
 class Precedence
 {
     [Text(Name = "renamedIgnoresNest")]
-    [Rename("renamedIgnoresJsonProperty"),JsonProperty("renamedIgnoresJsonProperty")]
+    [PropertyName("renamedIgnoresJsonProperty"),JsonProperty("renamedIgnoresJsonProperty")]
     public string RenamedOnConnectionSettings { get; set; } <1>
 
     [Text(Name = "nestAtt")]
-    [Rename("jsonProp"),JsonProperty("jsonProp")]
+    [PropertyName("nestProp"),JsonProperty("jsonProp")]
     public string NestAttribute { get; set; } <2>
 
-    [Rename("jsonProp"),JsonProperty("jsonProp")]
-    public string JsonProperty { get; set; } <3>
+    [PropertyName("nestProp"),JsonProperty("jsonProp")]
+    public string NestProperty { get; set; } <3>
 
-    [Rename("dontaskme"),JsonProperty("dontaskme")]
-    public string AskSerializer { get; set; } <4>
+    [JsonProperty("jsonProp")]
+    public string JsonProperty { get; set; } <4>
 
-    public string DefaultFieldNameInferrer { get; set; } <5>
+    [PropertyName("dontaskme"),JsonProperty("dontaskme")]
+    public string AskSerializer { get; set; } <5>
+
+    public string DefaultFieldNameInferrer { get; set; } <6>
 }
 ----
 <1> Even though this property has a NEST property mapping _and_ a `JsonProperty` attribute, We are going to provide a hard rename for it on ConnectionSettings later that should win.
-
-<2> This property has both a NEST attribute and a `JsonProperty`, NEST should win.
-
-<3> We should take the json property into account by itself
-
-<4> This property we are going to special case in our custom serializer to resolve to ask
-
-<5> We are going to register a DefaultFieldNameInferrer on ConnectionSettings that will uppercase all properties.
+<2> This property has both a NEST attribute and property and a `JsonProperty`, NEST should win.
+<3> This property has both a NEST property and a `JsonProperty`, NEST should win.
+<4> We should take the json property into account by itself
+<5> This property we are going to hard code in our custom serializer to resolve to ask.
+<6> We are going to register a DefaultFieldNameInferrer on ConnectionSettings that will uppercase all properties.
 
 Here we create a custom serializer that renames any property named `AskSerializer` to `ask`
 
@@ -511,6 +511,7 @@ var usingSettings = WithConnectionSettings(s => s
 
 usingSettings.Expect("renamed").ForField(Field<Precedence>(p => p.RenamedOnConnectionSettings));
 usingSettings.Expect("nestAtt").ForField(Field<Precedence>(p => p.NestAttribute));
+usingSettings.Expect("nestProp").ForField(Field<Precedence>(p => p.NestProperty));
 usingSettings.Expect("jsonProp").ForField(Field<Precedence>(p => p.JsonProperty));
 usingSettings.Expect("ask").ForField(Field<Precedence>(p => p.AskSerializer));
 usingSettings.Expect("DEFAULTFIELDNAMEINFERRER").ForField(Field<Precedence>(p => p.DefaultFieldNameInferrer));
@@ -525,12 +526,14 @@ usingSettings.Expect(new []
     "ask",
     "DEFAULTFIELDNAMEINFERRER",
     "jsonProp",
+    "nestProp",
     "nestAtt",
     "renamed"
 }).AsPropertiesOf(new Precedence
 {
     RenamedOnConnectionSettings = "renamed on connection settings",
     NestAttribute = "using a nest attribute",
+    NestProperty = "using a nest property",
     JsonProperty = "the default serializer resolves json property attributes",
     AskSerializer = "serializer fiddled with this one",
     DefaultFieldNameInferrer = "shouting much?"

docs/client-concepts/high-level/inference/indices-paths.asciidoc

@@ -88,7 +88,6 @@ singleIndexFromIndexName.Match(
 );
 ----
 <1> `_all` will override any specific index names here
-
 <2> The `Project` type has been mapped to a specific index name using <<index-name-type-mapping,`.DefaultMappingFor<Project>`>>
 
 [[nest-indices]]
@@ -121,9 +120,7 @@ ISearchRequest singleTypedRequest = new SearchDescriptor<Project>().Index(single
 var invalidSingleString = Index("name1, name2"); <3>
 ----
 <1> specifying a single index using a string
-
 <2> specifying a single index using a type
-
 <3> an **invalid** single index name
 
 ===== Multiple indices
@@ -149,9 +146,7 @@ manyStringRequest = new SearchDescriptor<Project>().Type(new[] { "name1", "name2
 ((IUrlParameter)manyStringRequest.Type).GetString(this.Client.ConnectionSettings).Should().Be("name1,name2");
 ----
 <1> specifying multiple indices using strings
-
 <2> specifying multiple indices using types
-
 <3> The index names here come from the Connection Settings passed to `TestClient`. See the documentation on <<index-name-inference, Index Name Inference>> for more details.
 
 ===== All Indices

docs/client-concepts/high-level/mapping/attribute-mapping.asciidoc

@@ -65,7 +65,7 @@ public class Employee
     public bool IsManager { get; set; }
 
     [Nested]
-    [Rename("empl"), JsonProperty("empl")]
+    [PropertyName("empl"), JsonProperty("empl")]
     public List<Employee> Employees { get; set; }
 }
 ----

docs/client-concepts/high-level/mapping/fluent-mapping.asciidoc

@@ -231,7 +231,7 @@ public class EmployeeWithAttributes
     public bool IsManager { get; set; }
 
     [Nested]
-    [Rename("empl"), JsonProperty("empl")]
+    [PropertyName("empl"), JsonProperty("empl")]
     public List<Employee> Employees { get; set; }
 }
 ----

docs/client-concepts/high-level/mapping/parent-child-relationships.asciidoc

@@ -99,11 +99,8 @@ var createIndexResponse = client.CreateIndex("index", c => c
 );
 ----
 <1> recommended to make the routing field mandatory so you can not accidentally forget
-
 <2> Map all of the `MyParent` properties
-
 <3> Map all of the `MyChild` properties
-
 <4> Additionally map the `JoinField` since it is not automatically mapped by `AutoMap()`
 
 We call `AutoMap()` for both types to discover properties of both .NET types. `AutoMap()` won't automatically setup the
@@ -179,7 +176,6 @@ parentDocument = new MyParent
 var indexParent = client.IndexDocument<MyDocument>(parentDocument);
 ----
 <1> this lets the join data type know this is a root document of type `myparent`
-
 <2> this lets the join data type know this is a root document of type `myparent`
 
 [source,javascript]

docs/client-concepts/high-level/serialization/extending-nest-types.asciidoc

@@ -0,0 +1,83 @@
+:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/6.1
+
+:github: https://github.com/elastic/elasticsearch-net
+
+:nuget: https://www.nuget.org/packages
+
+////
+IMPORTANT NOTE
+==============
+This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/ClientConcepts/HighLevel/Serialization/ExtendingNestTypes.doc.cs. 
+If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
+please modify the original csharp file found at the link and submit the PR with that change. Thanks!
+////
+
+[[extending-nest-types]]
+=== Extending NEST types
+
+Although of course NEST should always be up to date with a 100% API coverage of the Elasticsearch API, sometimes you might want to work around a bug
+or maybe use types from a third party plugin that NEST does not support.
+
+[source,csharp]
+----
+public class MyPluginProperty : IProperty
+{
+    IDictionary<string, object> IProperty.LocalMetadata { get; set; }
+    public string Type { get; set; } = "my_plugin_property";
+    public PropertyName Name { get; set; }
+
+    public MyPluginProperty(string name, string language)
+    {
+        this.Name = name;
+        this.Language = language;
+        this.Numeric = true;
+    }
+
+    [PropertyName("language")]
+    public string Language { get; set; }
+
+    [PropertyName("numeric")]
+    public bool Numeric { get; set; }
+}
+----
+
+`PropertyNameAttribute` can be used to mark properties that should be serialized. Without this attribute,
+NEST won't pick up the property for serialization.
+
+Now that we have our own `IProperty` implementation we can add it to our propertes mapping when creating an index
+
+[source,csharp]
+----
+var createIndexResponse = client.CreateIndex("myindex", c => c
+    .Mappings(ms => ms
+        .Map<Project>(m => m
+            .Properties(props => props
+                .Custom(new MyPluginProperty("fieldName", "dutch"))
+            )
+        )
+    )
+);
+----
+
+which will serialize to the following JSON request
+
+[source,javascript]
+----
+{
+  "mappings": {
+    "doc": {
+      "properties": {
+        "fieldName": {
+          "type": "my_plugin_property",
+          "language": "dutch",
+          "numeric": true
+        }
+      }
+    }
+  }
+}
+----
+
+Whilst NEST can serialize our `my_plugin_property`, it does not know how to deserialize it;
+We plan to make this more pluggable in the future
+

docs/high-level.asciidoc

@@ -96,6 +96,8 @@ own serializer, or by modifying how NEST's serializer behaves.
 
 * <<custom-serialization,Custom Serialization>>
 
+* <<extending-nest-types,Extending Nest Types>>
+
 * <<modifying-default-serializer,Modifying Default Serializer>>
 
 :includes-from-dirs: client-concepts/high-level/serialization
@@ -104,6 +106,8 @@ include::client-concepts/high-level/serialization/changing-serializers.asciidoc[
 
 include::client-concepts/high-level/serialization/custom-serialization.asciidoc[]
 
+include::client-concepts/high-level/serialization/extending-nest-types.asciidoc[]
+
 include::client-concepts/high-level/serialization/modifying-default-serializer.asciidoc[]
 
 [[mapping]]

src/Nest/CommonAbstractions/SerializationBehavior/Attributes/IgnoreAttribute.cs

@@ -0,0 +1,7 @@
+using System;
+
+namespace Nest
+{
+	[AttributeUsage(AttributeTargets.Property)]
+	public class IgnoreAttribute : Attribute { }
+}

…utes/MachineLearningDateTimeConverter.cs …utes/MachineLearningDateTimeAttribute.cssrc/Nest/CommonAbstractions/SerializationBehavior/Attributes/MachineLearningDateTimeConverter.cs renamed to src/Nest/CommonAbstractions/SerializationBehavior/Attributes/MachineLearningDateTimeAttribute.cs src/Nest/CommonAbstractions/SerializationBehavior/Attributes/MachineLearningDateTimeConverter.cs renamed to src/Nest/CommonAbstractions/SerializationBehavior/Attributes/MachineLearningDateTimeAttribute.cs

@@ -4,6 +4,12 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// Signals that this date time property is used in Machine learning API's some of which will always return the date as epoch.
+	/// </summary>
+	[AttributeUsage(AttributeTargets.Property)]
+	public class MachineLearningDateTimeAttribute : Attribute { }
+
 	internal class MachineLearningDateTimeConverter : IsoDateTimeConverter
 	{
 		private static readonly DateTimeOffset Epoch = new DateTimeOffset(1970, 1, 1, 0, 0, 0, 0, TimeSpan.Zero);