Skip to content

Commit 4a6e2e3

Browse files
maureimaurei
committed
documentation: usage guide
1 parent ab1f96d commit 4a6e2e3

33 files changed

+832
-659
lines changed

‎docs/usage/resources/hooks.md

Lines changed: 448 additions & 305 deletions
Large diffs are not rendered by default.

‎src/Examples/JsonApiDotNetCoreExample/Resources/ArticleResource.cs

Lines changed: 55 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,62 @@
55
using JsonApiDotNetCore.Models;
66
using JsonApiDotNetCore.Hooks;
77
using JsonApiDotNetCoreExample.Models;
8+
using Microsoft.Extensions.Logging;
9+
using System.Security.Principal;
810

9-
namespace JsonApiDotNetCoreExample.Resources
10-
{
11-
public class ArticleResource : ResourceDefinition<Article>
12-
{
13-
public override IEnumerable<Article> OnReturn(HashSet<Article> entities, ResourceAction pipeline)
14-
{
15-
if (pipeline == ResourceAction.GetSingle && entities.Single().Name == "Classified")
16-
{
17-
throw new JsonApiException(403, "You are not allowed to see this article!", new UnauthorizedAccessException());
18-
}
19-
return entities.Where(t => t.Name != "This should be not be included");
20-
}
21-
}
22-
}
11+
//namespace JsonApiDotNetCoreExample.Resources
12+
//{
13+
// public class ArticleResource : ResourceDefinition<Article>
14+
// {
15+
// public override IEnumerable<Article> OnReturn(HashSet<Article> entities, ResourcePipeline pipeline)
16+
// {
17+
// if (pipeline == ResourcePipeline.ReadSingle && entities.Single().Name == "Classified")
18+
// {
19+
// throw new JsonApiException(403, "You are not allowed to see this article!", new UnauthorizedAccessException());
20+
// }
21+
// return entities.Where(t => t.Name != "This should be not be included");
22+
// }
23+
// }
24+
//}
2325

2426

2527

28+
//namespace JsonApiDotNetCoreExample.Resources
29+
//{
30+
31+
// /// This is a scoped service, which means wil log will have a request-based
32+
// /// unique id associated to it.
33+
// public class UserActionsLogger : IUserActionsLogger
34+
// {
35+
// public ILogger GetLogger { get; private set; }
36+
// public UserActionsLogger(ILoggerFactory loggerFactory,
37+
// IUserService userService)
38+
// {
39+
// var userId = userService.GetUser().Id;
40+
// GetLogger = loggerFactory.CreateLogger($"[request: {Guid.NewGuid()}, user: {userId}] User Actions Log:");
41+
// }
42+
// }
43+
44+
// /// Resource definitions are also injected as scoped services.
45+
// public class ArticleResource : ResourceDefinition<Article>
46+
// {
47+
48+
// public override IEnumerable<Article> OnReturn(HashSet<Article> entities, ResourcePipeline pipeline)
49+
// {
50+
// return entities.Where(a => a.SoftDeleted == false);
51+
// }
52+
53+
// }
54+
55+
// public class PersonResource : ResourceDefinition<Person>
56+
// {
57+
// public override IEnumerable<Person> OnReturn(HashSet<Person> entities, ResourcePipeline pipeline)
58+
// {
59+
// if (pipeline == ResourcePipeline.Get || pipeline == ResourcePipeline.GetSingle)
60+
// {
61+
// return entities.Where(p => !p.WantsPrivacy);
62+
// }
63+
// return entities;
64+
// }
65+
// }
66+
//}

‎src/Examples/JsonApiDotNetCoreExample/Resources/PassportResource.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,17 @@ namespace JsonApiDotNetCoreExample.Resources
1010
{
1111
public class PassportResource : ResourceDefinition<Passport>
1212
{
13-
public override void BeforeRead(ResourceAction pipeline, bool nestedHook = false, string stringId = null)
13+
public override void BeforeRead(ResourcePipeline pipeline, bool nestedHook = false, string stringId = null)
1414
{
15-
if (pipeline == ResourceAction.GetSingle && nestedHook)
15+
if (pipeline == ResourcePipeline.ReadSingle && nestedHook)
1616
{
1717
throw new JsonApiException(403, "Not allowed to include passports on individual people", new UnauthorizedAccessException());
1818
}
1919
}
2020

21-
public override void BeforeImplicitUpdateRelationship(IUpdatedRelationshipHelper<Passport> relationshipHelper, ResourceAction pipeline)
21+
public override void BeforeImplicitUpdateRelationship(IAffectedRelationships<Passport> resourcesByRelationship, ResourcePipeline pipeline)
2222
{
23-
relationshipHelper.EntitiesRelatedTo<Person>().ToList().ForEach(kvp => DoesNotTouchLockedPassports(kvp.Value));
23+
resourcesByRelationship.GetByRelationship<Person>().ToList().ForEach(kvp => DoesNotTouchLockedPassports(kvp.Value));
2424
}
2525

2626
private void DoesNotTouchLockedPassports(IEnumerable<Passport> entities)

‎src/Examples/JsonApiDotNetCoreExample/Resources/PersonResource.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@ namespace JsonApiDotNetCoreExample.Resources
1010
{
1111
public class PersonResource : ResourceDefinition<Person>
1212
{
13-
public override IEnumerable<string> BeforeUpdateRelationship(HashSet<string> ids, IUpdatedRelationshipHelper<Person> relationshipHelper, ResourceAction pipeline)
13+
public override IEnumerable<string> BeforeUpdateRelationship(HashSet<string> ids, IAffectedRelationships<Person> resourcesByRelationship, ResourcePipeline pipeline)
1414
{
15-
BeforeImplicitUpdateRelationship(relationshipHelper, pipeline);
15+
BeforeImplicitUpdateRelationship(resourcesByRelationship, pipeline);
1616
return ids;
1717
}
1818

19-
public override void BeforeImplicitUpdateRelationship(IUpdatedRelationshipHelper<Person> relationshipHelper, ResourceAction pipeline)
19+
public override void BeforeImplicitUpdateRelationship(IAffectedRelationships<Person> resourcesByRelationship, ResourcePipeline pipeline)
2020
{
21-
relationshipHelper.EntitiesRelatedTo<Passport>().ToList().ForEach(kvp => DoesNotTouchLockedPeople(kvp.Value));
21+
resourcesByRelationship.GetByRelationship<Passport>().ToList().ForEach(kvp => DoesNotTouchLockedPeople(kvp.Value));
2222
}
2323

2424
private void DoesNotTouchLockedPeople(IEnumerable<Person> entities)

‎src/Examples/JsonApiDotNetCoreExample/Resources/TagResource.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ namespace JsonApiDotNetCoreExample.Resources
88
{
99
public class TagResource : ResourceDefinition<Tag>
1010
{
11-
public override IEnumerable<Tag> OnReturn(HashSet<Tag> entities, ResourceAction pipeline)
11+
public override IEnumerable<Tag> OnReturn(HashSet<Tag> entities, ResourcePipeline pipeline)
1212
{
1313
return entities.Where(t => t.Name != "This should be not be included");
1414
}

‎src/Examples/JsonApiDotNetCoreExample/Resources/TodoResource.cs

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
using System;
22
using System.Collections.Generic;
33
using System.Linq;
4-
using JsonApiDotNetCore.Hooks.Discovery;
54
using JsonApiDotNetCore.Internal;
65
using JsonApiDotNetCore.Models;
76
using JsonApiDotNetCore.Hooks;
@@ -11,17 +10,17 @@ namespace JsonApiDotNetCoreExample.Resources
1110
{
1211
public class TodoResource : ResourceDefinition<TodoItem>
1312
{
14-
public override void BeforeRead(ResourceAction pipeline, bool nestedHook = false, string stringId = null)
13+
public override void BeforeRead(ResourcePipeline pipeline, bool isIncluded = false, string stringId = null)
1514
{
1615
if (stringId == "1337")
1716
{
1817
throw new JsonApiException(403, "Not allowed to update author of any TodoItem", new UnauthorizedAccessException());
1918
}
2019
}
2120

22-
public override void BeforeImplicitUpdateRelationship(IUpdatedRelationshipHelper<TodoItem> relationshipHelper, ResourceAction pipeline)
21+
public override void BeforeImplicitUpdateRelationship(IAffectedRelationships<TodoItem> resourcesByRelationship, ResourcePipeline pipeline)
2322
{
24-
List<TodoItem> todos = relationshipHelper.EntitiesRelatedTo<Person>().SelectMany(kvp => kvp.Value).ToList();
23+
List<TodoItem> todos = resourcesByRelationship.GetByRelationship<Person>().SelectMany(kvp => kvp.Value).ToList();
2524
DoesNotTouchLocked(todos);
2625
}
2726

‎src/JsonApiDotNetCore/Hooks/Discovery/HooksDiscovery.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
using System.Collections.Generic;
33
using System.Linq;
44
using JsonApiDotNetCore.Graph;
5-
using JsonApiDotNetCore.Hooks.Discovery;
5+
using JsonApiDotNetCore.Hooks;
66
using JsonApiDotNetCore.Internal;
77
using JsonApiDotNetCore.Models;
88

‎src/JsonApiDotNetCore/Hooks/Execution/EntityDiff.cs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ namespace JsonApiDotNetCore.Hooks
1111
/// where the <see cref="IEntityDiff{TEntity}.DatabaseEntities"/> reflects what is the current state in the database.
1212
///
1313
/// Any relationships that are updated can be retrieved via the methods implemented on
14-
/// <see cref="IUpdatedRelationshipHelper{TDependent}"/>.
14+
/// <see cref="IAffectedRelationships{TDependent}"/>.
1515
/// </summary>
16-
public interface IEntityDiff<TEntity> : IUpdatedRelationshipHelper<TEntity> where TEntity : class, IIdentifiable
16+
public interface IEntityDiff<TEntity> : IAffectedRelationships<TEntity> where TEntity : class, IIdentifiable
1717
{
1818
HashSet<TEntity> RequestEntities { get; }
1919
HashSet<TEntity> DatabaseEntities { get; }

‎src/JsonApiDotNetCore/Hooks/Execution/HookExecutorHelper.cs

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@
66
using JsonApiDotNetCore.Data;
77
using JsonApiDotNetCore.Internal.Generics;
88
using JsonApiDotNetCore.Models;
9-
using JsonApiDotNetCore.Hooks;
109
using JsonApiDotNetCore.Extensions;
1110
using PrincipalType = System.Type;
1211
using DependentType = System.Type;
1312
using Microsoft.EntityFrameworkCore;
1413
using JsonApiDotNetCore.Services;
14+
using JsonApiDotNetCore.Internal;
1515

1616
namespace JsonApiDotNetCore.Hooks
1717
{
@@ -73,7 +73,6 @@ public IResourceHookContainer GetResourceHookContainer(DependentType dependentTy
7373
if (ShouldExecuteHook(dependentType, targetHook)) return container;
7474
}
7575
return null;
76-
7776
}
7877

7978
/// <inheritdoc/>
@@ -82,9 +81,6 @@ public IResourceHookContainer<TEntity> GetResourceHookContainer<TEntity>(Resourc
8281
return (IResourceHookContainer<TEntity>)GetResourceHookContainer(typeof(TEntity), hook);
8382
}
8483

85-
86-
87-
8884
public IEnumerable LoadDbValues(DependentType entityType, IEnumerable entities, ResourceHook hook, params RelationshipProxy[] relationships)
8985
{
9086
if (!ShouldLoadDbValues(entityType, hook)) return null;

‎src/JsonApiDotNetCore/Hooks/Execution/ResourceActionEnum.cs renamed to ‎src/JsonApiDotNetCore/Hooks/Execution/ResourcePipelineEnum.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@
55
/// is called from EntityResourceService.GetAsync(TId id), it will be called
66
/// with parameter pipeline = ResourceAction.GetSingle.
77
/// </summary>
8-
public enum ResourceAction
8+
public enum ResourcePipeline
99
{
1010
None,
11-
Get,
12-
GetSingle,
13-
GetRelationship,
11+
Read,
12+
ReadSingle,
13+
ReadRelationship,
1414
Create,
1515
Patch,
1616
PatchRelationship,

0 commit comments

Comments
 (0)