Skip to content

Commit 5414455

Browse files
markolbertmarkolbert
committed
update docs
1 parent 70c5607 commit 5414455

File tree

8 files changed

+503
-106
lines changed

8 files changed

+503
-106
lines changed

‎J4JMapLibrary/docs/authentication.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# J4JMapLibrary: Authentication
2+
3+
After creating a projection instance you call one of its authentication methods to enable using it:
4+
5+
```csharp
6+
public bool SetCredentials( TAuth credentials )
7+
8+
public async Task<bool> SetCredentialsAsync(
9+
TAuth credentials,
10+
CancellationToken ctx = default )
11+
```
12+
13+
Each service uses a different `TAuth` class:
14+
15+
|Service|TAuth Class|Details|
16+
|-------|-----------|-------|
17+
|Bing Maps|`BingCredentials`|`ApiKey` property holds API key|
18+
|Google Maps|`GoogleCredentials`|`ApiKey` property holds API key<br>`SignatureSecret` property holds your signature secret|
19+
|Open Street Maps|`OpenStreetCredentials`|`UserAgent` property holds user agent string|
20+
|Open Topo Maps|`OpenTopoCredentials`|`UserAgent` property holds user agent string|
21+
22+
The authentication methods return true if they succeed, false if they don't.
23+
24+
The only service where authentication might fail is Bing Maps, because Bing Maps requires interaction with the web to complete authentication and acquire various pieces of information required to access the service. That can fail for many reasons, including inability to access the web.
25+
26+
[return to table of contents](usage.md#overview)

‎J4JMapLibrary/docs/caching.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,44 @@
11
# J4JMapLibary: Caching
2+
3+
The `ITileCache` interface looks like this:
4+
5+
```csharp
6+
public interface ITileCache : IEnumerable<CachedEntry>
7+
{
8+
ITileCache? ParentCache { get; }
9+
CacheStats Stats { get; }
10+
11+
void Clear();
12+
void PurgeExpired();
13+
14+
Task<bool> LoadImageAsync( MapTile mapTile, CancellationToken ctx = default );
15+
Task<bool> AddEntryAsync( MapTile mapTile, CancellationToken ctx = default );
16+
}
17+
```
18+
19+
The caching system is designed to work in a tiered fashion, with each *level* of caching optinally calling upon a parent cache if it itself cannot satisfy the request for a map image.
20+
21+
The library comes with two caching classes: `MemoryCache` and `FileSystemCache`. What they do is pretty self-explanatory. Refer to the [caching documentation](caching.md) for more details on how to design your own cache.
22+
23+
You'd typically set up a multi-level caching system like this:
24+
25+
```csharp
26+
var tileFileCache = new FileSystemCache(LoggerFactory)
27+
{
28+
CacheDirectory = FileSystemCachePath,
29+
MaxBytes = FileSystemCacheSize <= 0 ? DefaultFileSystemCacheSize : FileSystemCacheSize,
30+
MaxEntries = FileSystemCacheEntries <= 0 ? DefaultFileSystemCacheEntries : FileSystemCacheEntries,
31+
RetentionPeriod = fileRetention
32+
};
33+
34+
if (!TimeSpan.TryParse(MemoryCacheRetention, out var memRetention))
35+
memRetention = TimeSpan.FromHours(1);
36+
37+
var tileMemCache = new MemoryCache(LoggerFactory)
38+
{
39+
MaxBytes = MemoryCacheSize <= 0 ? DefaultMemoryCacheSize : MemoryCacheSize,
40+
MaxEntries = MemoryCacheEntries <= 0 ? DefaultMemoryCacheEntries : MemoryCacheEntries,
41+
ParentCache = tileFileCache,
42+
RetentionPeriod = memRetention
43+
};
44+
```

‎J4JMapLibrary/docs/creating-a-projection.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# J4JMapLibrary: Creating a Projection Instance
2+
3+
To simplify obtaining a `Projection` instance I incorporated a factory method in the library. However, you can also obtain an instance by instantiating the projection yourself. These first few sections describe how to do that. To see how to use the factory approach, [jump to this section](usage.md#using-the-projection-factory).
4+
5+
Each service has its own unique projection class:
6+
7+
|Service|Projection Class|Constructor Parameters|
8+
|-------|----------------|----------------------|
9+
|Bing Maps|`BingMapsProjection`|`ILoggerFactory?` loggerFactory = null<br>`ITileCache?` tileCache = null|
10+
|Google Maps|`GoogleMapsProjection`|`ILoggerFactory?` loggerFactory = null|
11+
|Open Street Maps|`OpenStreetMapsProjection`|`ILoggerFactory?` loggerFactory = null<br>`ITileCache?` tileCache = null|
12+
|Open Topo Maps|`OpenTopoMapsProjection`|`ILoggerFactory?` loggerFactory = null<br>`ITileCache?` tileCache = null|
13+
14+
Three of the projections accept optional instances of `ITileCache` and `ILoggerFactory`. The `GoogleMapsProjection` constructor, however, only accepts an optional `ILoggerFactory`. That's because *the Google Maps Static API terms of use forbid caching the retrieved imagery.*
15+
16+
`ILoggerFactory` is simply an instance you obtain from Microsoft's logging service. Consult their documentation for details.
17+
18+
`ITileCache` is an instance of one or more classes that implement caching. For details, [consult the caching documentation](caching.md).
19+
20+
[return to table of contentes](usage.md#overview)

‎J4JMapLibrary/docs/custom-projections.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# J4JMapLibrary: Creating Custom Projections
2+
3+
A projection's name is defined by the `ProjectionAttribute` that decorates it:
4+
5+
```csharp
6+
[ Projection( "BingMaps" ) ]
7+
public sealed class BingMapsProjection : TiledProjection<BingCredentials>
8+
{
9+
//...
10+
}
11+
```

‎J4JMapLibrary/docs/factory.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# J4JMapLibrary: Using the Projection Factory
2+
3+
## Overview
4+
5+
- [Ensuring Your Credentials Can Be Found](#ensuring-your-credentials-can-be-found)
6+
- [Creating the Factory](#creating-the-factory)
7+
- [Creating a Projection](#creating-a-projection)
8+
- Custom Projections and Credentials
9+
- [Scanning for Custom Projections and Credentials](#scanning-for-custom-projections-and-credentials)
10+
- [Ensuring Custom Projections Can Be Found](#ensuring-custom-projections-can-be-found)
11+
12+
While it's fairly straightforward to create a projection, in order to make it possible to do so by choosing one of the caches at run time inspired me to write `ProjectionFactory`.
13+
14+
In order for the factory to work, however, two things are necessary:
15+
16+
- all authentication information must be available through the `IConfiguration` system; and,
17+
- you must have the factory scan whatever assemblies contain `Projection` classes. By default, the factory will scan the library itself, so the four default projections -- Bing Maps, Google Maps, Open Street Maps and Open Topo Maps -- will be included.
18+
19+
This is covered in more detail below.
20+
21+
## Ensuring Your Credentials Can Be Found
22+
23+
To make a projection's credential information available through the `IConfiguration` system, it must be organized in a configuration section called **Credentails**, further identified by the credentials's name. That's so the following code can work:
24+
25+
```csharp
26+
var retVal = Activator.CreateInstance( credType.CredentialsType )!;
27+
28+
var section = _config.GetSection( $"Credentials:{credType.Name}" );
29+
section.Bind( retVal );
30+
```
31+
32+
The built-in credentials have the following names:
33+
34+
|Credential Class|Name|
35+
|----------|----|
36+
|`BingCredentials`|BingMaps|
37+
|`GoogleCredentials`|GoogleMaps|
38+
|`OpenStreetCredentials`|OpenStreetMaps|
39+
|`OpenTopoCredentials`|OpenTopoMaps|
40+
41+
For more details on custom credentials and projections, consult the [documentation on how to create custom projections and credentials](custom-projections.md).
42+
43+
[return to table of contents](#overview)
44+
45+
[return to usage table of contents](usage.md#overview)
46+
47+
## Creating the Factory
48+
49+
The factory constructor takes the following parameters:
50+
51+
|Parameter|Parameter Description|
52+
|---------|---------------------|
53+
|`IConfiguration` config|provides access to the Microsoft configuration system|
54+
|`ILoggerFactory?` loggerFactory = null|optional; provides access to the Microsoft logging factory|
55+
|`bool` includeDefaults = true|default (true) is to scan the library itself|
56+
57+
*You must call `InitializeFactory()` before attempting to use it*. It returns `true` if at least one `Projection` class was found, `false` otherwise. Initialization is somewhat fragile because a lot of reflection is used in order to locate the projection classes and their corresponding credential classes.
58+
59+
[return to table of contents](#overview)
60+
61+
[return to usage table of contents](usage.md#overview)
62+
63+
## Creating a Projection
64+
65+
Once you've initialized the factory you can call one of its creation methods to obtain a projection, all of which return an instance of `ProjectionFactoryResult`. Each comes in both synchronous and asynchronous forms.
66+
67+
### CreateProjection(), CreateProjectionAsync()
68+
69+
|Parameter|Parameter Description|
70+
|---------|---------------------|
71+
|`string` projName|the name of the projection (see below)|
72+
|`ITileCache?` cache = null|the cache to use (optional); ignored for projections which don't support caching|
73+
|`string?` credentialsName = null|the name of the credentials class (optional)|
74+
|`bool` authenticate = true|controls whether or not to authenticate the projection after it's created (default: true)|
75+
76+
### Generic CreateProjection&lt;TProj&gt;(), CreateProjectionAsync&lt;TProj&gt;()
77+
78+
|Parameter|Parameter Description|
79+
|---------|---------------------|
80+
|`TProj`|the projection type (e.g., `BingMapsProjection`)|
81+
|`ITileCache?` cache = null|the cache to use (optional); ignored for projections which don't support caching|
82+
|`string?` credentialsName = null|the name of the credentials class (optional)|
83+
|`bool` authenticate = true|controls whether or not to authenticate the projection after it's created (default: true)|
84+
85+
### Type-based CreateProjection(), CreateProjectionAsync()
86+
87+
|Parameter|Parameter Description|
88+
|---------|---------------------|
89+
|`Type` projType|the projection type (e.g., `typeof(BingMapsProjection)`)|
90+
|`ITileCache?` cache = null|the cache to use (optional); ignored for projections which don't support caching|
91+
|`string?` credentialsName = null|the name of the credentials class (optional)|
92+
|`bool` authenticate = true|controls whether or not to authenticate the projection after it's created (default: true)|
93+
94+
The names of the built-in projections are as follows:
95+
96+
|Projection Class|Name|
97+
|----------|----|
98+
|`BingMapsProjection`|BingMaps|
99+
|`GoogleMapsProjection`|GoogleMaps|
100+
|`OpenStreetMapsProjection`|OpenStreetMaps|
101+
|`OpenTopoMapsProjection`|OpenTopoMaps|
102+
103+
[return to table of contents](#overview)
104+
[return to usage table of contents](usage.md#overview)
105+
106+
## Scanning for Custom Projections and Credentials
107+
108+
To have the factory include custom projection and credential classes you may have written you need to call one of the `ScanAssembly()` methods before calling `InitializeFactory()`. The `ScanAssemblies()` methods return the `ProjectionFactory` itself, so they can be daisy-chained.
109+
110+
[return to table of contents](#overview)
111+
112+
[return to usage table of contents](usage.md#overview)
113+
114+
## Ensuring Custom Projections Can Be Found
115+
116+
If you create a custom projection class you must deocrate it with a `ProjectionAttribute` in order for the factory to find it when it scans the assembly where it's defined. Here's an example of how the built-in `BingMapsProjection` class is named:
117+
118+
```csharp
119+
[ Projection( "BingMaps" ) ]
120+
public sealed class BingMapsProjection : TiledProjection<BingCredentials>
121+
```
122+
123+
Projection names must be unique within the application's environment, so be sure not to duplicate any of the built-in names:
124+
125+
|Projection Class|Name|
126+
|----------|----|
127+
|`BingMapsProjection`|BingMaps|
128+
|`GoogleMapsProjection`|GoogleMaps|
129+
|`OpenStreetMapsProjection`|OpenStreetMaps|
130+
|`OpenTopoMapsProjection`|OpenTopoMaps|
131+
132+
For more details on custom credentials and projections, consult the [documentation on how to create custom projections and credentials](custom-projections.md).
133+
134+
[return to table of contents](#overview)
135+
136+
[return to usage table of contents](usage.md#overview)

0 commit comments

Comments
 (0)