Request Resolution Documentation

Poster Content
nk4um User
Posts: 92
August 1, 2011 15:39Back to documentation

The solution for this ended up just being to set the grammar to accept both data-access/Books.xml and etc/system/Books.xml - no need for rewrite or additional endpoints.

Like · Post Reply
nk4um Moderator
Posts: 901
July 7, 2011 18:07

Hi Gary,

Just noticed that the video shorts have been uploaded and somehow seem to have been processed and have much longer play times than they really are. They're all actually around 5mins. Some of them are showing 40mins! I'll try to re-upload them tomorrow - but they're not that long really!

Incidentally we just posted an update to apposite in the repos. After you said you weren't synced with the repos we looked at the sync code.

We realised there was a trivial optimisation that allows the sync to only take any real time if there are changes in the repo. In which case, since its now cost free to sync when there are no changes, we've updated the cron frequency to check every three hours. Should mean that you really will see updates more quickly. (To get this you'll still have to manually sync ;-)

P.

Like · Post Reply
nk4um Moderator
Posts: 901
July 7, 2011 14:20

Apposite has a cron job that runs every 3 days to look for new updates. We only just pushed out the repo updates so your sampling rate was too low ...

http://localhost:1060/cron/panel

You could force it to fire from there if you like too ;-)

P.

Like · Post Reply
nk4um User
Posts: 92
July 7, 2011 14:15Found it

Hi Peter,

That worked. So the synchronize is used to get new modules. Up to now, I have always just gone in and Apposite has identified that there were updates. Because of that, I thought it was already doing a synchronization.

Gary

Like · Post Reply
nk4um Moderator
Posts: 901
July 7, 2011 14:11

Hi Gary

Did you synchronize with the repos? I just double checked an NKSE and NKEE production server and they both see it from the two repos.

http://localhost:1060/tools/apposite/admin/

and hit the "synchronize" button to fetch latest repo state.

P.

Like · Post Reply
nk4um User
Posts: 92
July 7, 2011 14:07No Apposite Install for Demo

Hi Peter,

I am not seeing an Apposite install for the Resolution Demo. I have a completely up to date Apposite install. There are no modules with the name resolution. There are some demo modules. for-each golden-thread grammer etc.

What am I missing?

Gary

Like · Post Reply
nk4um Moderator
Posts: 901
July 7, 2011 12:09Resolution Video Tutorial

Hi Gary,

I'd be very interested if you can take a look at this series of short-video tutorials on resolution...

http://docs.netkernel.org/book/view/book:tutorial:guide/doc:tutorial:resolution

If you update NK with apposite you'll also find these embedded in the documentation here...

http://localhost:1060/book/view/book:tutorial:guide/doc:tutorial:resolution

Again, I want to say thanks for taking the time to explain how you were not finding what you needed in the existing docs. Without this feedback we'd just be guessing which things we can improve.

Anyway if this helps you make progress then great - if not then we can look into specific details of your spaces.

Cheers,

Peter

Like · Post Reply
nk4um Moderator
Posts: 901
July 6, 2011 16:20

Hi Gary,

If this is urgent and is blocking progress then please send me a copy of your module.xml with comments at the point you need a hand. If its not and you can wait until tomorrow I'll have uploaded a set of 14 short video tutorials which I'd really appreciate your feedback on. Ideally I'd like to leave you in pain for another 24 hours to find out if the tutorials give you the information to solve your own problem (I'm hoping they will of course!)

Cheers,

Peter

PS Have got an evening of video editing and uploading ahead ;-)

Like · Post Reply
nk4um User
Posts: 92
July 6, 2011 13:22Still having problems

Hi Peter,

I am still having problems. What I am really trying to do is have 2 URI's that go to a single resource. res:/etc/system/Books.xml so that by convention I can hook up to the documentation and res:/data-access/Book, so that for each of my modules I can look at the dynamically created Books.xml from a browser.

So in essence, the impl for both resource identifiers is all in the same space, I am just unable to have 2 different identifiers without it seems recreating the whole request twice. My last try, in essence had both res:/etc/system/Books.xml and res:/data-access/Book in the same mapper where res:/data-access/Book set the request to res:/etc/system/Books.xml. When I did this, for some reason res:/etc/system/Books.xml was no longer found in the doc space, but only resolved to the XML Core Library - one of my imports.

Looking forward to seeing your documentation and examples.

Gary

Like · Post Reply
nk4um Moderator
Posts: 901
July 5, 2011 22:23

Hi Gary,

I've got an extensive reference guide and demo for resolution and am preparing some video tutorials that I hope will make all this stuff much more clear.

I will address your other issues soon, but quickly I can answer this question...

If I source res:/data-access/Book for the same space as I sourced etc/system/Books.xml I get a good response. When I display representation for /data-access/Book I get the expected response. But when I try get the result from /data-access/Book from etc/system/Books.xml

The fileset rewrite is not a general rewrite rule. Its just internal to the fileset endpoint, it is a convenience for certain patterns but the gist is that the regex pattern match can be rewritten to an alternative fileset path. It is never reissued into the address space. It is handled inside the fileset endpoint and must resolve to a file in the module's file structure.

The only way you can do the equivalent of NK3's rewriting of requests in NK4 is to use a mapper (or to write your own routing endpoint with a grammar and a mapped sub-request). Using the mapper, for example, this would do what you need for the dynamic docs resource...

<rootspace>
  <mapper>
    < !--rewrite mapping to dynamic docs-->
    <config>
      <endpoint>
        <grammar>res:/etc/system/Books.xml&lt;/grammar&gt;
        <request>res:/data-access/Book&lt;/request&gt;
      &lt;/endpoint&gt;
    &lt;/config&gt;
    <space> ... This inner mapped space needs to either import the space that has the res:/data-access/Book impl, or unlikely, to actually have the impl defined here. ... &lt;/space&gt;
  &lt;/mapper&gt;
&lt;/rootspace&gt;

I think this will sort out this particular confusion. Sorry, I think the confusion arose as a combination of NK3 legacy expectation and we need to add some extra clarification about what the point of the fileset rewrite convenience mode is for.

I'll send you links to the resolution material as soon as its ready - I have a set of isolated clear examples scenarios already and, with the help of this context you've shared, I have a sense of how we can do a better job of explaining the details.

As I said I'm going to create a series of short movies so that the resolution patterns can be illustrated with live use of the tools etc.

Please let me know if the doc service mapping sorts out that one issue.

Cheers,

Peter

Like · Post Reply
nk4um User
Posts: 92
July 5, 2011 21:37Another request trace issue

Take this example:

I have a module - Data Access with 3 spaces (main, doc and test). For the doc module I have:

<config>
  <import>res:/etc/system/DocumentationEndpoints.xml&lt;/import&gt;
&lt;/config&gt;
I have to define DocumentationEndPoints.xml somewhere. If I continue the above with
<mapper>
  <config>
    <import>res:/etc/system/DocumentationEndpoints.xml&lt;/import&gt;
  &lt;/config&gt;
  <space>
    <fileset>
      <regex>res:/etc/system/Documentation(ImportHook|Endpoints).xml&lt;/regex&gt;
    &lt;/fileset&gt;
    <fileset>
      <regex>res:/resources/.*doc.txt&lt;/regex&gt;
    &lt;/fileset&gt;
    <fileset>
      <regex>res:/service/mapper.gy&lt;/regex&gt;
    &lt;/fileset&gt;
    <fileset>
      <regex>res:/service/.*doc.txt&lt;/regex&gt;
    &lt;/fileset&gt;
  &lt;/space&gt;
&lt;/mapper&gt;
res:/etc/system/Documentation.xml resolves when I do a mapper based request, but does not resolve for the external request, which makes sense based on where I have defined it. However, it is not clear where the <config><import> is looking. I would think that it would be in the internal space since I am defining the mapper for the space and it would be able to find it there just like if I defined a request on the endpoint it would be in the inner space. However this is not how it works. I have to set the DocumentationEndpoint as a definition on the outerspace.

So once set in the outerspace, I do some request tracking. I source res:/etc/system/Books.xml and it resolves to an endpoint. I do Display Representation and I get the error /data-access/Book does not exist. Now I have a rewrite of

<fileset>
  <regex>res:/etc/system/Books.xml&lt;/regex&gt;
  <rewrite>res:/data-access/Book&lt;/rewrite&gt;
&lt;/fileset&gt;
If I source res:/data-access/Book for the same space as I sourced etc/system/Books.xml I get a good response. When I display representation for /data-access/Book I get the expected response. But when I try get the result from /data-access/Book from etc/system/Books.xml

The resulting XML is dynamic so that is likely part of the culprit, I just do not know why when I display representation through the request trace tool, I get different results for etc/system/Books.xml vs. /data-access/Book and all because of the rewrite.

Gary

Like · Post Reply
nk4um User
Posts: 92
July 5, 2011 19:59Still confused

Hi Peter,

I am confused as to whether I should have imports or filesets in the rootspace or in the mapper space. I also appear to have to import the same set of imports, groovy, layer1, freemarker, xrl, db etc in every space. It really feels like just hit or miss because I do not understand when it will use an import from the space I am in and when it will use an import from a space it is making a call too. From what I have done so far, it appears that if I have space A, and it calls an endpoint in space B then space A needs to know what functions are used by space B and make those imports into space A. I am consistently importing a set of 5 or 6 spaces into almost all my spaces because it resolves the Resolution errors.

Gary

Like · Post Reply
nk4um Moderator
Posts: 901
July 1, 2011 19:38

Hi Gary,

Hmmmm - thanks for posting this. It suggests we need to review the docs and maybe add some tutorials/videos on this aspect. The separation of resolution and execution is fundamental and powerful but I understand it can seem subtle.

Here's some tips.

  1. You're right that we made the default in NK4 that when a request hits the end of an address space it will try to go up the superstack (since in most cases this is the pattern you need - especially in libraries etc). However if this isn't what you want we provided a more powerful way of terminating resolution with the limiter endpoint - which allows you to use grammars to provide broad or specific termination of resolution.
  2. When sorting out resolution its really important to probe the address space with test requests. This allows you to test your assumptions about imports and grammars etc and usually saves a lot of headaches. The request trace tool allows you to inject requests and see the results in different phases. Usually once you probed a space with a test request you can convert that request to a unit test and leave it in place to give you confidence that the space is stable and as you specified it.
  3. Resolution order happens in cardinal order - starting at the top of a space and trying all endpoint in declaration order. An import (or a mapper, or overlay) is an endpoint that will delegate its resolution to the space that it maps to. If an import is at a higher level than some other endpoint it will get the chance to resolve the request first.
  4. Resolution is not determined by a space only by endpoints. If an endpoint accepts the resolution then the kernel stops the resolution process at that point and moves to forming an execution request and issuing it to that endpoint.

I guess one of the subtleties when moving from NK3 to NK4 is that we don't force rewriting of requests onto the edge of a module/space. This can be done anywhere and its done with the mapper - which always must have a space to which it maps. If its helpful you could replicate the NK3 pattern exactly by just having a space with a single mapper in it - then just consider the inner space as the same as an NK3 space used to be.

Hope this helps. If it doesn't and you're still not clear then send me an email and we can find a good time to go through the specifics of your spaces and help out.

Cheers and enjoy the holiday weekend,

Peter

PS Thanks again - this is really valuable information, we are often too close to this stuff and it helps to understand how we can do better to explain it. We'll take this on board and add some more tutorial material to help.

Like · Post Reply
nk4um User
Posts: 92
July 1, 2011 18:45Request Resolution Documentation

Where would I find documentation that describes the request resolution process in NK4. For NK3 I had a better understanding as it was based on module and you could either import, or bounce back up the stack using <super/>. With NK4 and the spaces I am not quite as clear. I have a space that calls into another space. Space A does not have any calls to freemarker. It calls into Space B with a request that does call freemarker. However, I get a resolution failure if space A does not have freemarker imported. If I import freemarker into Space A, then it works.

I tried to create a common space that could have some common NK imports and import that space to working spaces. This works for XUnit tests as per demo etc. However, if I try and do it for other spaces, it does not work, I have to explicitly import the same set of spaces in each of the spaces. And if you leave one out, e.g. freemarker, it will not resolve.

Gary

Like · Post Reply