This is an automated email from the ASF dual-hosted git repository. nightowl888 pushed a commit to branch docs/codec-configuration in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit 82125dfa4f5596735173804547d861c19ee7e96e Author: Shad Storhaug <[email protected]> AuthorDate: Sun May 31 22:58:08 2020 +0700 Added documentation demonstrating how codec factories can be subclassed, custom built, and registered to include custom codec types, as well as testing examples, and default registered codecs. (closes #266, closes LUCENENET-625) --- src/Lucene.Net/Codecs/package.md | 324 ++++++++++++++++++++- .../Support/Codecs/DefaultCodecFactory.cs | 99 +++++-- .../Codecs/DefaultDocValuesFormatFactory.cs | 98 +++++-- .../Support/Codecs/DefaultPostingsFormatFactory.cs | 98 +++++-- src/Lucene.Net/Support/Codecs/ICodecFactory.cs | 10 +- .../Support/Codecs/IDocValuesFormatFactory.cs | 10 +- .../Support/Codecs/IPostingsFormatFactory.cs | 10 +- 7 files changed, 575 insertions(+), 74 deletions(-) diff --git a/src/Lucene.Net/Codecs/package.md b/src/Lucene.Net/Codecs/package.md index eea6fd4..7258e25 100644 --- a/src/Lucene.Net/Codecs/package.md +++ b/src/Lucene.Net/Codecs/package.md @@ -1,4 +1,4 @@ ---- +--- uid: Lucene.Net.Codecs summary: *content --- @@ -22,13 +22,327 @@ summary: *content Codecs API: API for customization of the encoding and structure of the index. - The Codec API allows you to customise the way the following pieces of index information are stored: * Postings lists - see <xref:Lucene.Net.Codecs.PostingsFormat> * DocValues - see <xref:Lucene.Net.Codecs.DocValuesFormat> * Stored fields - see <xref:Lucene.Net.Codecs.StoredFieldsFormat> * Term vectors - see <xref:Lucene.Net.Codecs.TermVectorsFormat> * FieldInfos - see <xref:Lucene.Net.Codecs.FieldInfosFormat> * SegmentInfo - see <xref:Lucene.Net.Codecs.SegmentInfoFormat> * Norms - see < [...] + The Codec API allows you to customize the way the following pieces of index information are stored: + +* Postings lists - see <xref:Lucene.Net.Codecs.PostingsFormat> +* DocValues - see <xref:Lucene.Net.Codecs.DocValuesFormat> +* Stored fields - see <xref:Lucene.Net.Codecs.StoredFieldsFormat> +* Term vectors - see <xref:Lucene.Net.Codecs.TermVectorsFormat> +* FieldInfos - see <xref:Lucene.Net.Codecs.FieldInfosFormat> +* SegmentInfo - see <xref:Lucene.Net.Codecs.SegmentInfoFormat> +* Norms - see <xref:Lucene.Net.Codecs.NormsFormat> +* Live documents - see <xref:Lucene.Net.Codecs.LiveDocsFormat> For some concrete implementations beyond Lucene's official index format, see the [Codecs module]({@docRoot}/../codecs/overview-summary.html). - Codecs are identified by name through the Java Service Provider Interface. To create your own codec, extend <xref:Lucene.Net.Codecs.Codec> and pass the new codec's name to the super() constructor: public class MyCodec extends Codec { public MyCodec() { super("MyCodecName"); } ... } You will need to register the Codec class so that the {@link java.util.ServiceLoader ServiceLoader} can find it, by including a META-INF/services/org.apache.lucene.codecs.Codec file on your classpath that con [...] + Codecs are identified by name through the <xref:Lucene.Net.Codecs.ICodecFactory> implementation, which by default is the <xref:Lucene.Net.Codecs.DefaultCodecFactory>. To create your own codec, extend <xref:Lucene.Net.Codecs.Codec>. By default, the name of the class (minus the suffix "Codec") will be used as the codec's name. + + public class MyCodec : Codec // By default, the name will be "My" because the "Codec" suffix is removed + { + } + + + > **NOTE:** There is a built-in <xref:Lucene.Net.Codecs.FilterCodec> type that can be used to easily extend an existing codec type. + + To override the default codec name, decorate the custom codec with the <xref:Lucene.Net.Codecs.CodecNameAttribute>. + + The <xref:Lucene.Net.Codecs.CodecNameAttribute> can be used to set the name to that of a built-in codec to override its registration in the <xref:Lucene.Net.Codecs.DefaultCodecFactory>. + + [CodecName("MyCodec")] // Sets the codec name explicitly + public class MyCodec : Codec + { + } + + Register the Codec class so Lucene.NET can find it either by providing it to the <xref:Lucene.Net.Codecs.DefaultCodecFactory> at application start up or by using a dependency injection container. + +## Using Microsoft.Extensions.DependencyInjection to Register a Custom Codec + + First, create an <xref:Lucene.Net.Codecs.ICodecFactory> implementation to return the type based on a string name. Here is a generic implementation, that can be used with almost any dependency injection container. + + public class NamedCodecFactory : ICodecFactory, IServiceListable + { + private readonly IDictionary<string, Codec> codecs; + + public NamedCodecFactory(IEnumerable<Codec> codecs) + { + this.codecs = codecs.ToDictionary(n => n.Name); + } + + public ICollection<string> AvailableServices => codecs.Keys; + + public Codec GetCodec(string name) + { + if (codecs.TryGetValue(name, out Codec value)) + return value; + + throw new ArgumentException($"The codec {name} is not registered.", nameof(name)); + } + } + + > Implementing <xref:Lucene.Net.Util.IServiceListable> is optional. This allows for logging scenarios (such as those built into the test framework) to list the codecs that are registered. + + Next, register all of the codecs that your Lucene.NET implementation will use and the `NamedCodecFactory` with dependency injection using singleton lifetime. + + IServiceProvider services = new ServiceCollection() + .AddSingleton<Codec, Lucene.Net.Codecs.Lucene46.Lucene46Codec>() + .AddSingleton<Codec, MyCodec>() + .AddSingleton<ICodecFactory, NamedCodecFactory>() + .BuildServiceProvider(); + + Finally, set the <xref:Lucene.Net.Codecs.ICodecFactory> implementation Lucene.NET will use with the static [Codec.SetCodecFactory(ICodecFactory)](xref:Lucene.Net.Codecs.Codec) method. This must be done one time at application start up. + + Codec.SetCodecFactory(services.GetService<ICodecFactory>()); + +## Using <xref:Lucene.Net.Codecs.DefaultCodecFactory> to Register a Custom Codec + +If your application is not using dependency injection, you can register a custom codec by adding your codec at start up. + + Codec.SetCodecFactory(new DefaultCodecFactory { + CustomCodecTypes = new Type[] { typeof(MyCodec) } + }); + +Note that <xref:Lucene.Net.Codecs.DefaultCodecFactory> also registers all built-in codec types automatically. + +## Custom Postings Formats + + If you just want to customize the <xref:Lucene.Net.Codecs.PostingsFormat>, or use different postings formats for different fields. + + [PostingsFormatName("MyPostingsFormat")] + public class MyPostingsFormat : PostingsFormat + { + private readonly string field; + + public MyPostingsFormat(string field) + { + this.field = field ?? throw new ArgumentNullException(nameof(field)); + } + + public override FieldsConsumer FieldsConsumer(SegmentWriteState state) + { + // Returns fields consumer... + } + + public override FieldsProducer FieldsProducer(SegmentReadState state) + { + // Returns fields producer... + } + } + + Extend the the default <xref:Lucene.Net.Codecs.Lucene46.Lucene46Codec>, and override [GetPostingsFormatForField(string)](xref:Lucene.Net.Codecs.Lucene46.Lucene46Codec) to return your custom postings format. + + [CodecName("MyCodec")] + public class MyCodec : Lucene46Codec + { + public override PostingsFormat GetPostingsFormatForField(string field) + { + return new MyPostingsFormat(field); + } + } + + Registration of a custom postings format is similar to registering custom codecs, implement <xref:Lucene.Net.Codecs.IPostingsFormatFactory> and then call <xref:Lucene.Net.Codecs.PostingsFormat.SetPostingsFormatFactory(xref:Lucene.Net.Codecs.IPostingsFormatFactory)> at application start up. + + PostingsFormat.SetPostingsFormatFactory(new DefaultPostingsFormatFactory { + CustomPostingsFormatTypes = new Type[] { typeof(MyPostingsFormat) } + }); + +## Custom DocValues Formats + + Similarly, if you just want to customize the <xref:Lucene.Net.Codecs.DocValuesFormat> per-field, have a look at [GetDocValuesFormatForField(string)](xref:Lucene.Net.Codecs.Lucene46.Lucene46Codec). Custom implementations can be provided by implementing <xref:Lucene.Net.Codecs.IDocValuesFormatFactory> and registering the factory using <xref:Lucene.Net.Codecs.DocValuesFormat.SetDocValuesFormatFactory(xref:Lucene.Net.Codecs.IDocValuesFormatFactory)>. + +## Testing Custom Codecs + + The <xref:Lucene.Net.TestFramework> library contains specialized classes to minimize the amount of code required to thoroughly test extensions to Lucene.NET. Create a new class library project targeting an executable framework your consumers will be using and add the following NuGet package reference. The test framework uses NUnit as the test runner. + + > See [Unit testing C# with NUnit and .NET Core](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-with-nunit) for detailed instructions on how to set up a class library to use with NUnit. + + > .NET Standard is not an executable target. Tests will not run unless you target a framework such as `netcoreapp3.1` or `net48`. + + Here is an example project file for .NET Core 3.1 for testing a project named `MyCodecs.csproj`. + + <Project Sdk="Microsoft.NET.Sdk"> + + <PropertyGroup> + <TargetFramework>netcoreapp3.1</TargetFramework> + </PropertyGroup> + + <ItemGroup> + <PackageReference Include="nunit" Version="3.9.0" /> + <PackageReference Include="NUnit3TestAdapter" Version="3.16.0" /> + <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.4.0" /> + <PackageReference Include="Lucene.Net.TestFramework" Version="4.8.0-beta00008" /> + <PackageReference Include="System.Net.Primitives" Version="4.3.0"/> + </ItemGroup> + + <ItemGroup> + <ProjectReference Include="..\MyCodecs\MyCodecs.csproj" /> + </ItemGroup> + + </Project> + + > This example outlines testing a custom <xref:Lucene.Net.Codecs.PostingsFormat>, but testing other codec dependencies is a similar procedure. + + To extend an existing codec with a new <xref:Lucene.Net.Codecs.PostingsFormat>, the <xref:Lucene.Net.Codecs.FilterCodec> class can be subclassed and the codec to be extended supplied to the <xref:Lucene.Net.Codecs.FilterCodec> constructor. A <xref:Lucene.Net.Codecs.PostingsFormat> should be supplied to an existing codec to run the tests against it. + + This example is for testing a custom postings format named `MyPostingsFormat`. Creating a postings format is a bit involved, but an overview of the process is in [Building a new Lucene postings format ](http://blog.mikemccandless.com/2012/07/building-new-lucene-postings-format.html). + + public class MyCodec : FilterCodec + { + private readonly PostingsFormat myPostingsFormat; + + public MyCodec() + : base(new Lucene.Net.Codecs.Lucene46.Lucene46Codec()) + { + myPostingsFormat = new MyPostingsFormat(); + } + } + + Next, add a class to the test project and decorate it with the `TestFixtureAttribute` from NUnit. To test a postings format, subclass <xref:Lucene.Net.Index.BasePostingsFormatTestCase>, override the `GetCodec()` method, and return the codec under test. The codec can be cached in a member variable to improve the performance of the tests. + + namespace ExampleLuceneNetTestFramework + { + [TestFixture] + public class TestMyPostingsFormat : BasePostingsFormatTestCase + { + private readonly Codec codec = new MyCodec(); + + protected override Codec GetCodec() + { + return codec; + } + } + } + + The <xref:Lucene.Net.Index.BasePostingsFormatTestCase> class includes a barrage of 8 tests that can now be run using your favorite test runner, such as Visual Studio Test Explorer. + + - TestDocsAndFreqs + - TestDocsAndFreqsAndPositions + - TestDocsAndFreqsAndPositionsAndOffsets + - TestDocsAndFreqsAndPositionsAndOffsetsAndPayloads + - TestDocsAndFreqsAndPositionsAndPayloads + - TestDocsOnly + - TestMergeStability + - TestRandom + + The goal of the <xref:Lucene.Net.Index.BasePostingsFormatTestCase> is that if all of these tests pass, then the <xref:Lucene.Net.Codecs.PostingsFormat> will always be compatible with Lucene.NET. + +## Registering Codecs with the Test Framework + + Codecs, postings formats and doc values formats can be injected into the test framework to integration test them against other Lucene.NET components. This is an advanced scenario that assumes integration tests for Lucene.NET components exist in your test project. + + In your test project, add a new file to the root of the project named `Startup.cs`. Remove any namespaces from the + file, but leave the `Startup` class and inherit <xref:Lucene.Net.Util.LuceneTestFrameworkInitializer>. + + public class Startup : LuceneTestFrameworkInitializer + { + /// <summary> + /// Runs before all tests in the current assembly + /// </summary> + protected override void TestFrameworkSetUp() + { + CodecFactory = new TestCodecFactory { + CustomCodecTypes = new Codec[] { typeof(MyCodec) } + }; + } + } + +## Setting the Default Codec for use in Tests + + The above block will register a new codec named `MyCodec` with the test framework. However, the test framework will not select the codec for use in tests on its own. To override the default behavior of selecting a random codec, the configuration parameter `tests:codec` must be set explicitly. + + > A codec name is derived from either the name of the class (minus the "Codec" suffix) or the <xref:Lucene.Net.Codecs.CodecName.Name> property. + +#### Setting the Default Codec using an Environment Variable + + Set an environment variable named `lucene:tests:codec` to the name of the codec. + + $env:lucene:tests:codec = "MyCodec"; # Powershell example + +#### Setting the Default Codec using a Configuration File + + Add a file to the test project (or a parent directory of the test project) named `lucene.testsettings.json` with a value named `tests:codec`. + + { + "tests": { + "codec": "MyCodec" + } + } + +## Setting the Default Postings Format or Doc Values Format for use in Tests + + Similarly to codecs, the default postings format or doc values format can be set via environment variable or configuration file. + +#### Environment Variables + + Set environment variables named `lucene:tests:postingsformat` to the name of the postings format and/or `lucene:tests:docvaluesformat` to the name of the doc values format. + + $env:lucene:tests:postingsformat = "MyPostingsFormat"; # Powershell example + $env:lucene:tests:docvaluesformat = "MyDocValuesFormat"; # Powershell example + +#### Configuration File + + Add a file to the test project (or a parent directory of the test project) named `lucene.testsettings.json` with a value named `tests:postingsformat` and/or `tests:docvaluesformat`. + + { + "tests": { + "postingsformat": "MyPostingsFormat", + "docvaluesformat": "MyDocValuesFormat" + } + } + +## Default Codec Configuration + + For reference, the default configuration of codecs, postings formats, and doc values are as follows. + + #### Codecs + + These are the types registered by the <xref:Lucene.Net.Codecs.DefaultCodecFactory> by default. + + | Name | Type | Assembly | + | ---- | ---- | -------- | + | `Lucene46` | <xref:Lucene.Net.Codecs.Lucene46.Lucene46Codec> | Lucene.Net.dll | + | `Lucene3x` | <xref:Lucene.Net.Codecs.Lucene3x.Lucene3xCodec> | Lucene.Net.dll | + | `Lucene45` | <xref:Lucene.Net.Codecs.Lucene45.Lucene45Codec> | Lucene.Net.dll | + | `Lucene42` | <xref:Lucene.Net.Codecs.Lucene42.Lucene42Codec> | Lucene.Net.dll | + | `Lucene41` | <xref:Lucene.Net.Codecs.Lucene41.Lucene41Codec> | Lucene.Net.dll | + | `Lucene40` | <xref:Lucene.Net.Codecs.Lucene40.Lucene40Codec> | Lucene.Net.dll | + | `Appending` | <xref:Lucene.Net.Codecs.Appending.AppendingCodec> | Lucene.Net.Codecs.dll | + | `SimpleText` | <xref:Lucene.Net.Codecs.SimpleText.SimpleTextCodec> | Lucene.Net.Codecs.dll | + + > The codecs in Lucene.Net.Codecs.dll are only loaded if referenced in the calling project. + +#### Postings Formats + + These are the types registered by the <xref:Lucene.Net.Codecs.DefaultPostingsFormatFactory> by default. + + | Name | Type | Assembly | + | ---- | ---- | -------- | + | `Lucene41` | <xref:Lucene.Net.Codecs.Lucene41.Lucene41PostingsFormat> | Lucene.Net.dll | + | `Lucene40` | <xref:Lucene.Net.Codecs.Lucene40.Lucene40PostingsFormat> | Lucene.Net.dll | + | `SimpleText` | <xref:Lucene.Net.Codecs.SimpleText.SimpleTextPostingsFormat> | Lucene.Net.Codecs.dll | + | `Pulsing41` | <xref:Lucene.Net.Codecs.Pulsing.Pulsing41PostingsFormat> | Lucene.Net.Codecs.dll | + | `Direct` | <xref:Lucene.Net.Codecs.Memory.DirectPostingsFormat> | Lucene.Net.Codecs.dll | + | `FSTOrd41` | <xref:Lucene.Net.Codecs.Memory.FSTOrdPostingsFormat> | Lucene.Net.Codecs.dll | + | `FSTOrdPulsing41` | <xref:Lucene.Net.Codecs.Memory.FSTOrdPulsing41PostingsFormat> | Lucene.Net.Codecs.dll | + | `FST41` | <xref:Lucene.Net.Codecs.Memory.FSTPostingsFormat> | Lucene.Net.Codecs.dll | + | `FSTPulsing41` | <xref:Lucene.Net.Codecs.Memory.FSTPulsing41PostingsFormat> | Lucene.Net.Codecs.dll | + | `Memory` | <xref:Lucene.Net.Codecs.Memory.MemoryPostingsFormat> | Lucene.Net.Codecs.dll | + | `BloomFilter` | <xref:Lucene.Net.Codecs.Bloom.BloomFilteringPostingsFormat> | Lucene.Net.Codecs.dll | + + > The postings formats in Lucene.Net.Codecs.dll are only loaded if referenced in the calling project. + +#### Doc Values Formats + + These are the types registered by the <xref:Lucene.Net.Codecs.DefaultDocValuesFormatFactory> by default. - If you just want to customise the <xref:Lucene.Net.Codecs.PostingsFormat>, or use different postings formats for different fields, then you can register your custom postings format in the same way (in META-INF/services/org.apache.lucene.codecs.PostingsFormat), and then extend the default <xref:Lucene.Net.Codecs.Lucene46.Lucene46Codec> and override [#getPostingsFormatForField(String)](xref:Lucene.Net.Codecs.Lucene46.Lucene46Codec) to return your custom postings format. + | Name | Type | Assembly | + | ---- | ---- | -------- | + | `Lucene45` | <xref:Lucene.Net.Codecs.Lucene45.Lucene45DocValuesFormat> | Lucene.Net.dll | + | `Lucene42` | <xref:Lucene.Net.Codecs.Lucene42.Lucene42DocValuesFormat> | Lucene.Net.dll | + | `Lucene40` | <xref:Lucene.Net.Codecs.Lucene40.Lucene40DocValuesFormat> | Lucene.Net.dll | + | `SimpleText` | <xref:Lucene.Net.Codecs.SimpleText.SimpleTextDocValuesFormat> | Lucene.Net.Codecs.dll | + | `Direct` | <xref:Lucene.Net.Codecs.Memory.DirectDocValuesFormat> | Lucene.Net.Codecs.dll | + | `Memory` | <xref:Lucene.Net.Codecs.Memory.MemoryDocValuesFormat> | Lucene.Net.Codecs.dll | + | `Disk` | <xref:Lucene.Net.Codecs.DiskDV.DiskDocValuesFormat> | Lucene.Net.Codecs.dll | - Similarly, if you just want to customise the <xref:Lucene.Net.Codecs.DocValuesFormat> per-field, have a look at [#getDocValuesFormatForField(String)](xref:Lucene.Net.Codecs.Lucene46.Lucene46Codec). \ No newline at end of file + > The doc values formats in Lucene.Net.Codecs.dll are only loaded if referenced in the calling project. diff --git a/src/Lucene.Net/Support/Codecs/DefaultCodecFactory.cs b/src/Lucene.Net/Support/Codecs/DefaultCodecFactory.cs index 02931f5..4161e8e 100644 --- a/src/Lucene.Net/Support/Codecs/DefaultCodecFactory.cs +++ b/src/Lucene.Net/Support/Codecs/DefaultCodecFactory.cs @@ -23,29 +23,86 @@ namespace Lucene.Net.Codecs */ /// <summary> - /// LUCENENET specific class that implements the default functionality for the - /// <see cref="ICodecFactory"/>. + /// Implements the default functionality of <see cref="ICodecFactory"/>. /// <para/> - /// The most common use cases are: - /// <list type="bullet"> - /// <item><description>Initialize <see cref="DefaultCodecFactory"/> with a set of <see cref="CustomCodecTypes"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultCodecFactory"/> and override - /// <see cref="DefaultCodecFactory.GetCodec(Type)"/> so an external dependency injection - /// container can be used to supply the instances (lifetime should be singleton). Note that you could - /// alternately use the "named type" feature that many DI containers have to supply the type based on name by - /// overriding <see cref="GetCodec(string)"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultCodecFactory"/> and override - /// <see cref="DefaultCodecFactory.GetCodecType(string)"/> so a type new type can be - /// supplied that is not in the <see cref="DefaultCodecFactory.codecNameToTypeMap"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultCodecFactory"/> to add new or override the default <see cref="Codec"/> - /// types by overriding <see cref="Initialize()"/> and calling <see cref="PutCodecType(Type)"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultCodecFactory"/> to scan additional assemblies for <see cref="Codec"/> - /// subclasses in by overriding <see cref="Initialize()"/> and calling <see cref="ScanForCodecs(Assembly)"/>. - /// For performance reasons, the default behavior only loads Lucene.Net codecs.</description></item> - /// </list> + /// To replace the <see cref="DefaultCodecFactory"/> instance, call + /// <see cref="Codec.SetCodecFactory(ICodecFactory)"/> at application start up. + /// <see cref="DefaultCodecFactory"/> can be subclassed or passed additional parameters to register + /// additional codecs, inject dependencies, or change caching behavior, as shown in the following examples. + /// Alternatively, <see cref="ICodecFactory"/> can be implemented to provide complete control over + /// codec creation and lifetimes. /// <para/> - /// To set the <see cref="ICodecFactory"/>, call <see cref="Codec.SetCodecFactory(ICodecFactory)"/>. + /// <h4>Register Additional Codecs</h4> + /// <para/> + /// Additional codecs can be added by initializing the instance of <see cref="DefaultCodecFactory"/> and + /// passing an array of <see cref="Codec"/>-derived types. + /// <code> + /// // Register the factory at application start up. + /// Codec.SetCodecFactory(new DefaultCodecFactory { + /// CustomCodecTypes = new Type[] { typeof(MyCodec), typeof(AnotherCodec) } + /// }); + /// </code> + /// <para/> + /// <h4>Only Use Explicitly Defined Codecs</h4> + /// <para/> + /// <see cref="PutCodecType(Type)"/> can be used to explicitly add codec types. In this example, + /// the call to <c>base.Initialize()</c> is excluded to skip the built-in codec registration. + /// Since <c>AnotherCodec</c> doesn't have a default constructor, the <see cref="NewCodec(Type)"/> + /// method is overridden to supply the required parameters. + /// <code> + /// public class ExplicitCodecFactory : DefaultCodecFactory + /// { + /// protected override void Initialize() + /// { + /// // Load specific codecs in a specific order. + /// PutCodecType(typeof(MyCodec)); + /// PutCodecType(typeof(AnotherCodec)); + /// } + /// + /// protected override Codec NewCodec(Type type) + /// { + /// // Special case: AnotherCodec has a required dependency + /// if (typeof(AnotherCodec).Equals(type)) + /// return new AnotherCodec(new SomeDependency()); + /// + /// return base.NewCodec(type); + /// } + /// } + /// + /// // Register the factory at application start up. + /// Codec.SetCodecFactory(new ExplicitCodecFactory()); + /// </code> + /// See the <see cref="Lucene.Net.Codecs"/> namespace documentation for more examples of how to + /// inject dependencies into <see cref="Codec"/> subclasses. + /// <para/> + /// <h4>Use Reflection to Scan an Assembly for Codecs</h4> + /// <para/> + /// <see cref="ScanForCodecs(Assembly)"/> or <see cref="ScanForCodecs(IEnumerable{Assembly})"/> can be used + /// to scan assemblies using .NET Reflection for codec types and add all subclasses that are found automatically. + /// This example calls <c>base.Initialize()</c> to load the default codecs prior to scanning for additional codecs. + /// <code> + /// public class ScanningCodecFactory : DefaultCodecFactory + /// { + /// protected override void Initialize() + /// { + /// // Load all default codecs + /// base.Initialize(); + /// + /// // Load all of the codecs inside of the same assembly that MyCodec is defined in + /// ScanForCodecs(typeof(MyCodec).Assembly); + /// } + /// } + /// + /// // Register the factory at application start up. + /// Codec.SetCodecFactory(new ScanningCodecFactory()); + /// </code> + /// Codecs in the target assemblie(s) can be excluded from the scan by decorating them with + /// the <see cref="ExcludeCodecFromScanAttribute"/>. /// </summary> + /// <seealso cref="ICodecFactory"/> + /// <seealso cref="IServiceListable"/> + /// <seealso cref="ExcludeCodecFromScanAttribute"/> + // LUCENENET specific public class DefaultCodecFactory : NamedServiceFactory<Codec>, ICodecFactory, IServiceListable { private static readonly Type[] localCodecTypes = new Type[] { @@ -226,7 +283,7 @@ namespace Lucene.Net.Codecs if (name == null) throw new ArgumentNullException(nameof(name)); EnsureInitialized(); - if (!codecNameToTypeMap.TryGetValue(name, out Type codecType) && codecType == null) + if (!codecNameToTypeMap.TryGetValue(name, out Type codecType) || codecType == null) { throw new ArgumentException($"Codec '{name}' cannot be loaded. If the codec is not " + $"in a Lucene.Net assembly, you must subclass {typeof(DefaultCodecFactory).FullName}, " + diff --git a/src/Lucene.Net/Support/Codecs/DefaultDocValuesFormatFactory.cs b/src/Lucene.Net/Support/Codecs/DefaultDocValuesFormatFactory.cs index 95beae1..aa8f799 100644 --- a/src/Lucene.Net/Support/Codecs/DefaultDocValuesFormatFactory.cs +++ b/src/Lucene.Net/Support/Codecs/DefaultDocValuesFormatFactory.cs @@ -23,29 +23,85 @@ namespace Lucene.Net.Codecs */ /// <summary> - /// LUCENENET specific class that implements the default functionality for the - /// <see cref="IDocValuesFormatFactory"/>. + /// Implements the default functionality of <see cref="IDocValuesFormatFactory"/>. /// <para/> - /// The most common use cases are: - /// <list type="bullet"> - /// <item><description>Initialize <see cref="DefaultDocValuesFormatFactory"/> with a set of <see cref="CustomDocValuesFormatTypes"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultDocValuesFormatFactory"/> and override - /// <see cref="DefaultDocValuesFormatFactory.GetDocValuesFormat(Type)"/> so an external dependency injection - /// container can be used to supply the instances (lifetime should be singleton). Note that you could - /// alternately use the "named type" feature that many DI containers have to supply the type based on name by - /// overriding <see cref="GetDocValuesFormat(string)"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultDocValuesFormatFactory"/> and override - /// <see cref="DefaultDocValuesFormatFactory.GetDocValuesFormatType(string)"/> so a type new type can be - /// supplied that is not in the <see cref="DefaultDocValuesFormatFactory.docValuesFormatNameToTypeMap"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultDocValuesFormatFactory"/> to add new or override the default <see cref="DocValuesFormat"/> - /// types by overriding <see cref="Initialize()"/> and calling <see cref="PutDocValuesFormatType(Type)"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultDocValuesFormatFactory"/> to scan additional assemblies for <see cref="DocValuesFormat"/> - /// subclasses in by overriding <see cref="Initialize()"/> and calling <see cref="ScanForDocValuesFormats(Assembly)"/>. - /// For performance reasons, the default behavior only loads Lucene.Net codecs.</description></item> - /// </list> + /// To replace the <see cref="DefaultDocValuesFormatFactory"/> instance, call + /// <see cref="DocValuesFormat.SetDocValuesFormatFactory(IDocValuesFormatFactory)"/> at application start up. + /// <see cref="DefaultDocValuesFormatFactory"/> can be subclassed or passed additional parameters to register + /// additional codecs, inject dependencies, or change caching behavior, as shown in the following examples. + /// Alternatively, <see cref="IDocValuesFormatFactory"/> can be implemented to provide complete control over + /// doc values format creation and lifetimes. /// <para/> - /// To set the <see cref="IDocValuesFormatFactory"/>, call <see cref="DocValuesFormat.SetDocValuesFormatFactory(IDocValuesFormatFactory)"/>. + /// <h4>Register Additional DocValuesFormats</h4> + /// <para/> + /// Additional codecs can be added by initializing the instance of <see cref="DefaultDocValuesFormatFactory"/> and + /// passing an array of <see cref="DocValuesFormat"/>-derived types. + /// <code> + /// // Register the factory at application start up. + /// DocValuesFormat.SetDocValuesFormatFactory(new DefaultDocValuesFormatFactory { + /// CustomDocValuesFormatTypes = new Type[] { typeof(MyDocValuesFormat), typeof(AnotherDocValuesFormat) } + /// }); + /// </code> + /// <para/> + /// <h4>Only Use Explicitly Defined DocValuesFormats</h4> + /// <para/> + /// <see cref="PutDocValuesFormatType(Type)"/> can be used to explicitly add codec types. In this example, + /// the call to <c>base.Initialize()</c> is excluded to skip the built-in codec registration. + /// Since <c>AnotherDocValuesFormat</c> doesn't have a default constructor, the <see cref="NewDocValuesFormat(Type)"/> + /// method is overridden to supply the required parameters. + /// <code> + /// public class ExplicitDocValuesFormatFactory : DefaultDocValuesFormatFactory + /// { + /// protected override void Initialize() + /// { + /// // Load specific codecs in a specific order. + /// PutDocValuesFormatType(typeof(MyDocValuesFormat)); + /// PutDocValuesFormatType(typeof(AnotherDocValuesFormat)); + /// } + /// + /// protected override DocValuesFormat NewDocValuesFormat(Type type) + /// { + /// // Special case: AnotherDocValuesFormat has a required dependency + /// if (typeof(AnotherDocValuesFormat).Equals(type)) + /// return new AnotherDocValuesFormat(new SomeDependency()); + /// + /// return base.NewDocValuesFormat(type); + /// } + /// } + /// + /// // Register the factory at application start up. + /// DocValuesFormat.SetDocValuesFormatFactory(new ExplicitDocValuesFormatFactory()); + /// </code> + /// See the <see cref="Lucene.Net.Codecs"/> namespace documentation for more examples of how to + /// inject dependencies into <see cref="DocValuesFormat"/> subclasses. + /// <para/> + /// <h4>Use Reflection to Scan an Assembly for DocValuesFormats</h4> + /// <para/> + /// <see cref="ScanForDocValuesFormats(Assembly)"/> or <see cref="ScanForDocValuesFormats(IEnumerable{Assembly})"/> can be used + /// to scan assemblies using .NET Reflection for codec types and add all subclasses that are found automatically. + /// <code> + /// public class ScanningDocValuesFormatFactory : DefaultDocValuesFormatFactory + /// { + /// protected override void Initialize() + /// { + /// // Load all default codecs + /// base.Initialize(); + /// + /// // Load all of the codecs inside of the same assembly that MyDocValuesFormat is defined in + /// ScanForDocValuesFormats(typeof(MyDocValuesFormat).Assembly); + /// } + /// } + /// + /// // Register the factory at application start up. + /// DocValuesFormat.SetDocValuesFormatFactory(new ScanningDocValuesFormatFactory()); + /// </code> + /// Doc values formats in the target assembly can be excluded from the scan by decorating them with + /// the <see cref="ExcludeDocValuesFormatFromScanAttribute"/>. /// </summary> + /// <seealso cref="IDocValuesFormatFactory"/> + /// <seealso cref="IServiceListable"/> + /// <seealso cref="ExcludeDocValuesFormatFromScanAttribute"/> + // LUCENENET specific public class DefaultDocValuesFormatFactory : NamedServiceFactory<DocValuesFormat>, IDocValuesFormatFactory, IServiceListable { private static readonly Type[] localDocValuesFormatTypes = new Type[] { @@ -223,7 +279,7 @@ namespace Lucene.Net.Codecs if (name == null) throw new ArgumentNullException(nameof(name)); EnsureInitialized(); - if (!docValuesFormatNameToTypeMap.TryGetValue(name, out Type codecType) && codecType == null) + if (!docValuesFormatNameToTypeMap.TryGetValue(name, out Type codecType) || codecType == null) { throw new ArgumentException($"DocValuesFormat '{name}' cannot be loaded. If the format is not " + $"in a Lucene.Net assembly, you must subclass {typeof(DefaultDocValuesFormatFactory).FullName}, " + diff --git a/src/Lucene.Net/Support/Codecs/DefaultPostingsFormatFactory.cs b/src/Lucene.Net/Support/Codecs/DefaultPostingsFormatFactory.cs index f377d75..e1a42ac 100644 --- a/src/Lucene.Net/Support/Codecs/DefaultPostingsFormatFactory.cs +++ b/src/Lucene.Net/Support/Codecs/DefaultPostingsFormatFactory.cs @@ -23,29 +23,85 @@ namespace Lucene.Net.Codecs */ /// <summary> - /// LUCENENET specific class that implements the default functionality for the - /// <see cref="IPostingsFormatFactory"/>. + /// Implements the default functionality of <see cref="IPostingsFormatFactory"/>. /// <para/> - /// The most common use cases are: - /// <list type="bullet"> - /// <item><description>Initialize <see cref="DefaultPostingsFormatFactory"/> with a set of <see cref="CustomPostingsFormatTypes"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultPostingsFormatFactory"/> and override - /// <see cref="DefaultPostingsFormatFactory.GetPostingsFormat(Type)"/> so an external dependency injection - /// container can be used to supply the instances (lifetime should be singleton). Note that you could - /// alternately use the "named type" feature that many DI containers have to supply the type based on name by - /// overriding <see cref="GetPostingsFormat(string)"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultPostingsFormatFactory"/> and override - /// <see cref="DefaultPostingsFormatFactory.GetPostingsFormatType(string)"/> so a type new type can be - /// supplied that is not in the <see cref="DefaultPostingsFormatFactory.postingsFormatNameToTypeMap"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultPostingsFormatFactory"/> to add new or override the default <see cref="PostingsFormat"/> - /// types by overriding <see cref="Initialize()"/> and calling <see cref="PutPostingsFormatType(Type)"/>.</description></item> - /// <item><description>Subclass <see cref="DefaultPostingsFormatFactory"/> to scan additional assemblies for <see cref="PostingsFormat"/> - /// subclasses in by overriding <see cref="Initialize()"/> and calling <see cref="ScanForPostingsFormats(Assembly)"/>. - /// For performance reasons, the default behavior only loads Lucene.Net codecs.</description></item> - /// </list> + /// To replace the <see cref="DefaultPostingsFormatFactory"/> instance, call + /// <see cref="PostingsFormat.SetPostingsFormatFactory(IPostingsFormatFactory)"/> at application start up. + /// <see cref="DefaultPostingsFormatFactory"/> can be subclassed or passed additional parameters to register + /// additional codecs, inject dependencies, or change caching behavior, as shown in the following examples. + /// Alternatively, <see cref="IPostingsFormatFactory"/> can be implemented to provide complete control over + /// postings format creation and lifetimes. /// <para/> - /// To set the <see cref="IPostingsFormatFactory"/>, call <see cref="PostingsFormat.SetPostingsFormatFactory(IPostingsFormatFactory)"/>. + /// <h4>Register Additional PostingsFormats</h4> + /// <para/> + /// Additional codecs can be added by initializing the instance of <see cref="DefaultPostingsFormatFactory"/> and + /// passing an array of <see cref="PostingsFormat"/>-derived types. + /// <code> + /// // Register the factory at application start up. + /// PostingsFormat.SetPostingsFormatFactory(new DefaultPostingsFormatFactory { + /// CustomPostingsFormatTypes = new Type[] { typeof(MyPostingsFormat), typeof(AnotherPostingsFormat) } + /// }); + /// </code> + /// <para/> + /// <h4>Only Use Explicitly Defined PostingsFormats</h4> + /// <para/> + /// <see cref="PutPostingsFormatType(Type)"/> can be used to explicitly add codec types. In this example, + /// the call to <c>base.Initialize()</c> is excluded to skip the built-in codec registration. + /// Since <c>AnotherPostingsFormat</c> doesn't have a default constructor, the <see cref="NewPostingsFormat(Type)"/> + /// method is overridden to supply the required parameters. + /// <code> + /// public class ExplicitPostingsFormatFactory : DefaultPostingsFormatFactory + /// { + /// protected override void Initialize() + /// { + /// // Load specific codecs in a specific order. + /// PutPostingsFormatType(typeof(MyPostingsFormat)); + /// PutPostingsFormatType(typeof(AnotherPostingsFormat)); + /// } + /// + /// protected override PostingsFormat NewPostingsFormat(Type type) + /// { + /// // Special case: AnotherPostingsFormat has a required dependency + /// if (typeof(AnotherPostingsFormat).Equals(type)) + /// return new AnotherPostingsFormat(new SomeDependency()); + /// + /// return base.NewPostingsFormat(type); + /// } + /// } + /// + /// // Register the factory at application start up. + /// PostingsFormat.SetPostingsFormatFactory(new ExplicitPostingsFormatFactory()); + /// </code> + /// See the <see cref="Lucene.Net.Codecs"/> namespace documentation for more examples of how to + /// inject dependencies into <see cref="PostingsFormat"/> subclasses. + /// <para/> + /// <h4>Use Reflection to Scan an Assembly for PostingsFormats</h4> + /// <para/> + /// <see cref="ScanForPostingsFormats(Assembly)"/> or <see cref="ScanForPostingsFormats(IEnumerable{Assembly})"/> can be used + /// to scan assemblies using .NET Reflection for codec types and add all subclasses that are found automatically. + /// <code> + /// public class ScanningPostingsFormatFactory : DefaultPostingsFormatFactory + /// { + /// protected override void Initialize() + /// { + /// // Load all default codecs + /// base.Initialize(); + /// + /// // Load all of the codecs inside of the same assembly that MyPostingsFormat is defined in + /// ScanForPostingsFormats(typeof(MyPostingsFormat).Assembly); + /// } + /// } + /// + /// // Register the factory at application start up. + /// PostingsFormat.SetPostingsFormatFactory(new ScanningPostingsFormatFactory()); + /// </code> + /// Postings formats in the target assembly can be excluded from the scan by decorating them with + /// the <see cref="ExcludePostingsFormatFromScanAttribute"/>. /// </summary> + /// <seealso cref="IPostingsFormatFactory"/> + /// <seealso cref="IServiceListable"/> + /// <seealso cref="ExcludePostingsFormatFromScanAttribute"/> + // LUCENENET specific public class DefaultPostingsFormatFactory : NamedServiceFactory<PostingsFormat>, IPostingsFormatFactory, IServiceListable { private static readonly Type[] localPostingsFormatTypes = new Type[] @@ -223,7 +279,7 @@ namespace Lucene.Net.Codecs if (name == null) throw new ArgumentNullException(nameof(name)); EnsureInitialized(); - if (!postingsFormatNameToTypeMap.TryGetValue(name, out Type codecType) && codecType == null) + if (!postingsFormatNameToTypeMap.TryGetValue(name, out Type codecType) || codecType == null) { throw new ArgumentException($"PostingsFormat '{name}' cannot be loaded. If the format is not " + $"in a Lucene.Net assembly, you must subclass {typeof(DefaultPostingsFormatFactory).FullName}, " + diff --git a/src/Lucene.Net/Support/Codecs/ICodecFactory.cs b/src/Lucene.Net/Support/Codecs/ICodecFactory.cs index 8d0e9d0..79f3df2 100644 --- a/src/Lucene.Net/Support/Codecs/ICodecFactory.cs +++ b/src/Lucene.Net/Support/Codecs/ICodecFactory.cs @@ -1,4 +1,6 @@ -namespace Lucene.Net.Codecs +using Lucene.Net.Util; + +namespace Lucene.Net.Codecs { /* * Licensed to the Apache Software Foundation (ASF) under one or more @@ -18,12 +20,16 @@ */ /// <summary> - /// LUCENENET specific contract for extending the functionality of <see cref="Codec"/> implementations so + /// Contract for extending the functionality of <see cref="Codec"/> implementations so /// they can be injected with dependencies. /// <para/> /// To set the <see cref="ICodecFactory"/>, call <see cref="Codec.SetCodecFactory(ICodecFactory)"/>. + /// <para/> + /// See the <see cref="Lucene.Net.Codecs"/> namespace documentation for some common usage examples. /// </summary> /// <seealso cref="DefaultCodecFactory"/> + /// <seealso cref="IServiceListable"/> + // LUCENENET specific public interface ICodecFactory { /// <summary> diff --git a/src/Lucene.Net/Support/Codecs/IDocValuesFormatFactory.cs b/src/Lucene.Net/Support/Codecs/IDocValuesFormatFactory.cs index 2c30d47..36d3a4f 100644 --- a/src/Lucene.Net/Support/Codecs/IDocValuesFormatFactory.cs +++ b/src/Lucene.Net/Support/Codecs/IDocValuesFormatFactory.cs @@ -1,4 +1,6 @@ -namespace Lucene.Net.Codecs +using Lucene.Net.Util; + +namespace Lucene.Net.Codecs { /* * Licensed to the Apache Software Foundation (ASF) under one or more @@ -18,12 +20,16 @@ */ /// <summary> - /// LUCENENET specific contract for extending the functionality of <see cref="DocValuesFormat"/> implementations so + /// Contract for extending the functionality of <see cref="DocValuesFormat"/> implementations so /// they can be injected with dependencies. /// <para/> /// To set the <see cref="IDocValuesFormatFactory"/>, call <see cref="DocValuesFormat.SetDocValuesFormatFactory(IDocValuesFormatFactory)"/>. + /// <para/> + /// See the <see cref="Lucene.Net.Codecs"/> namespace documentation for some common usage examples. /// </summary> /// <seealso cref="DefaultDocValuesFormatFactory"/> + /// <seealso cref="IServiceListable"/> + // LUCENENET specific public interface IDocValuesFormatFactory { /// <summary> diff --git a/src/Lucene.Net/Support/Codecs/IPostingsFormatFactory.cs b/src/Lucene.Net/Support/Codecs/IPostingsFormatFactory.cs index 46ceced..76a066b 100644 --- a/src/Lucene.Net/Support/Codecs/IPostingsFormatFactory.cs +++ b/src/Lucene.Net/Support/Codecs/IPostingsFormatFactory.cs @@ -1,4 +1,6 @@ -namespace Lucene.Net.Codecs +using Lucene.Net.Util; + +namespace Lucene.Net.Codecs { /* * Licensed to the Apache Software Foundation (ASF) under one or more @@ -18,12 +20,16 @@ */ /// <summary> - /// LUCENENET specific contract for extending the functionality of <see cref="PostingsFormat"/> implementations so + /// Contract for extending the functionality of <see cref="PostingsFormat"/> implementations so /// they can be injected with dependencies. /// <para/> /// To set the <see cref="IPostingsFormatFactory"/>, call <see cref="PostingsFormat.SetPostingsFormatFactory(IPostingsFormatFactory)"/>. + /// <para/> + /// See the <see cref="Lucene.Net.Codecs"/> namespace documentation for some common usage examples. /// </summary> /// <seealso cref="DefaultPostingsFormatFactory"/> + /// <seealso cref="IServiceListable"/> + // LUCENENET specific public interface IPostingsFormatFactory { /// <summary>
