Future data portal redesign

[rockfordlhotka]

Between @TheCakeMonster and @swegele, I've started thinking that maybe a future data portal API and implementation is something to consider (maybe for CSLA 9).

Take @TheCakeMonster 's comment on a thread and @swegele 's comments in this thread as a start.

As I mentioned to @swegele, if I'd thought about the data portal as a service API the way I think about those things today - but back in 1997 or 2001 - I think we'd have something a lot more like what @TheCakeMonster is talking about. The data portal would provide exactly three possible results:

1. Success result with what you asked for
2. Success result saying why it can't return or do what you asked
3. Exception because something truly exceptional happened (like network failure, etc.)

The current data portal pretty much lumps numbers 2 and 3 together, which is very awkward.

Sure, there could be numerous workarounds to solve this using the current data portal. The easiest being an abstraction using what amounts to a Unit of Work (UOW) pattern where you use the data portal to always interact with one DataPortalOperation<T> type.

Basically, do to the data portal what the data portal does to http/gprc/wcf/etc. Abstract it away.

And that might be what this future implementation will do too, because one of my primary requirements in this potential rethink is to leave the existing data portal functionality alone. I don't want to break literally every CSLA app out there! Any data portal redesign needs to be opt in, so people can ignore it, migrate to it over time, or adopt it how they choose.

Calling Code

I'd like this new data portal to always return a consistent type, maybe like this:

  public class DataPortalResult<R, F>
  {
    public bool Succeeded { get; private set; }
    public R Success { get; private set; }
    public F Failure { get; private set; }
 }

Or an exception - basically today's DataPortalException, but only in the case of a true exception.

This means someone calling the data portal would do something like this (to show the concept):

@inject IDataPortal<R, F> portal

// ...

try
{
  var result = await portal.FetchAsync();
  if (result.Succeeded)
  {
    person = result.Success;
    // use domain object as we do today
  }
  else
  {
    reason = result.Failure;
    // now we can know why the request failed in whatever
    // level of detail we decide to provide to the caller
  }
}
catch (DataPortalException ex)
{
  // something truly unexpected happened, and this has (for debug anyway)
  // the server->client stack trace, ErrorInfo with exception details, etc.
}
catch (Exception ex)
{
  // something REALLY truly unexpected happened and the data portal
  // itself failed in a way it wasn't even able to return a DataPortalException
}

On the Server

I'm not sure the server-side code can change a lot. It does need to change so it can create and return the "failure" type for the call.

The thing that can't really change is the use of exceptions to indicate failure, because we rely on that to roll back transactions in ADO.NET, Dapper, EF, etc. Pretty much all the data access frameworks out there rely on exceptions to trigger a rollback.

I must confess that I haven't thought through the detail on this yet - exactly what a data portal operation will look like. But perhaps something with a "context" parameter?

  [Fetch]
  private void Fetch(int id, [Inject]OperationContext context)
  {
    // load data as we do today
    context.Success(this);

    // if, for some reason, we decide we can't load the data
    // like because the user isn't authorized, instead of a SecurityException
    // we'd do this
    context.Failure(new PersonFailure("You aren't worthy!");
  }

Realistically, that context.Success(this) call shouldn't be necessary, as that'd be the default behavior, barring an exception. If context.Failure() is called, that'd override the default behavior, and only return the failure object.

[swegele]

I will be happy to help with this effort in any way I can as things progress.

To start, let me share a different pattern I implemented in my LOB app and business objects which removes the need for the front-end UI/app developer to know anything about the DataPortal. They only need to inject ApplicationContext.

Here is the code in a Blazor Component calling an editable business object:

@inject NotificationService _notifSvc;
@inject Csla.ApplicationContext _appContext;

...

try
{
  var labToEdit = BL.LabEdit.GetLab(_appContext, labId);
  ...
}
catch (Exception ex)
{
  _notificationService.AddErrorNotification(ex);
}

Here is the factory code in that business object:

  public static LabEdit NewLab(ApplicationContext appContext)
  {
      var newObj = GetDataPortal(appContext).Create();

      newObj.BusinessRules.CheckRules();

      return newObj;
  }

  public static LabEdit GetLab(ApplicationContext appContext, string id)
  {
      var newObj = GetDataPortal(appContext).Fetch(id);

      newObj.BusinessRules.CheckRules();
      return newObj;
  }
...

Here is the GetDataPortal method in the base class for root business objects:

[Serializable()]
public abstract class MyRootBusinessBase<T> : MyCommonBusinessBase<T>
    where T : MyRootBusinessBase<T>
{
    protected static IDataPortal<T> GetDataPortal(ApplicationContext appContext)
    {
        var portalFactory = appContext.GetRequiredService<IDataPortalFactory>();
        var portal = portalFactory.GetPortal<T>();
        return portal;
    }
    ...
}

I don't want to lose that simplicity....(too early but at this point) but I expect I'd be looking for ways to use abstraction to put your numbers 2 and 3 back together again so that every CRUD call does not require 4 separate checks (success with object 1, success no object 2, failure 3, dp failure 4). This abstraction layer could take care of any further "sanitizing" in line with the concerns so clearly expressed by @TheCakeMonster while putting separate things back into one simple Exception scenario (what you wanted to happen didn't happen).

[ajohnstone-ks]

IMO #2 and #3 aren't different though; I think that exceptions are warranted when the method cannot fulfil its contract. Take for example a method GetOrderById. Whether that's due to a network issue, or a user asking for object id 1353 which doesn't exist, the method didn't do what was expected of it. The only difference would be the error message we'd show the user.

Separating them means you need to check for result codes and handle exceptions.

Just wanted to say that, but if this does move forward I'm glad to hear it would be opt-in :-)

[swegele]

Good point @ajohnstone-ks and I agree. To your point about gladness for "opt-in", I have an existing app with 300+ screens and lots of business objects. Most of these are not currently coded to distinguish between errors of type 2 and 3. Arguably they should when the feature is made available. So I'm pondering:

• opt in to the new dataportal style (when it's ready)
• abstract it so my existing forms/objects continue to work as they are now (pass/exception) but can eventually be enhanced
• start gradual migration of forms/objects to make use of the 4 response types

Looking forward to a lot of good stuff coming. I'm still trying to digest all the changes in .NET 8 this week!

[rockfordlhotka]

The distinction between 2 and 3 is at the core of the discussion.

Long ago there was a discussion about how the data portal should return one of:

• The requested object
• null
• An exception

The problem with returning null is that you get no detail about why your request was denied. Not failed, because that'd be an exceptional result. But denied, because that's not exceptional and yet happens.

The more evolved suggestion (most recently by @TheCakeMonster) is to return a "result" that either provides the requested value or the reason why the request couldn't be completed. Or, in exceptional cases, an exception.

I've argued that this is to be closer to what everyone should be doing with service implementations, and I agree with that.

What's interesting is that the object/null/exception approach isn't that far off the old idea that procedures should return 1, 0, or -1 to indicate yes, no, exception - and that goes back decades. And there were variations on that theme, with different negative numbers providing different "result codes", etc.

Many years ago I thought about (and in some old forum talked about) the idea of an "object portal". A more general purpose superset of what we think of as the data portal.

Basically, an object portal takes mobile objects to another level by (in my mind):

1. Allowing you to ask the portal to perform an operation on an object graph
2. Based on the nature of the requested operation, the object portal might move the graph to another machine
   1. The graph might not move if the resources for the operation are local
   2. The graph might move to another machine, but only machine(s) that have the resources required for the operation
3. As you can imagine, this means there's a way to discover machines (servers) and which resources exist on each machine
4. Also there's a way for any operation to be annotated with the resources required for the operation
5. An "operation" is an aribtrary verb - not just create/fetch/update/etc.

[ajohnstone-ks]

Yes, the obj/null/exception did immediately bring to mind the 1, 0, -1 of the C days. IIRC, one of the issues is that people ignore the result codes. In our code base I still see many calls to, for example, dr.Read() where the bool result is just completely ignored. Often that makes the later code blow up.

From my perspective An "operation" is an arbitrary verb - not just create/fetch/update/etc. is the cause of the issue how the data portal should return one of: The requested object/null/An exception

If the verbs are viewed as contracts and not arbitrary operations, I think the question goes away. Create/Fetch return either the BO requested or an exception is thrown; null is not a valid answer. Same with Insert/Update really, due to the nature of the mobile objects where they can be changed on the server, the BO saved needs to come back.

Executes may or may not return data, but if the BO executes successfully it comes back; maybe it just doesn't have any additional data with it, it depends on the specific command, but either the command object itself comes back (success, with optional new data) or the operation fails and just an exception comes back.

[rockfordlhotka]

And, of course, what's fun is that inside the data portal today there is a result object/message that comes back from the server. Always, unless there's a network exception.

The server may throw an exception, but it is caught on the server and serialized back to the client. If that happens, then the client throws a DataPortalException that wraps all the server detail.

Or the server may return a valid result, which is then handed back to the client-side calling code.

So behind the scenes, the data portal already does what @TheCakeMonster is talking about - but it is abstracted away to be the current model where you either get back an object or an exception.

[ajohnstone-ks]

So most of the work is done! I'm not against this, again, provided its opt-in. We will be struggling enough to update our code to get to Csla 6. Its a very old (like 2003 or so) Csla codebase. But I do like discussing these things, and I would not like to be forced to deal with result codes. :-) Thank for all your work on this, Csla is my favorite framework to use.