I am having some trouble mentally digesting your manual on LLBLGen Pro 2.6. Some parts of it is a little more opaque than others (or maybe I am just too thick or just too tired at the present). Anyway on the section of using context (page 205) I find a little (no make that a lot) confusing. I am not sure what its purpose is. Its not much use in asp.net as this is stateless, its not an object cache so what would one really use it for.

Obviously there must be a good reason for its existence or you guys would not have added it in.

Can you give a _**good example **_of where using a context really provides some functionality that cannot or is difficult to implement by another means?

A good clear example of how one would use this is the real world (not just how to set it up/use it in code) would be good.

Also I am finding some of your terminology a little hard to get my head around. You talk in terms of graphs, projections, injections and so forth. For the intellectually challenged (of which I am a prime example) maybe you could add a glossary of terms used so that us lessor mortals do not waste time trying to acertain what concepts are being discussed when I just want to use this stuff. For example what does "The context class, available in ORM support classes, represent a semantic context in your program" actually mean? I can actually follow most the dialog used by Sir Humphrey in the old "Yes Minister" British TV Series, but some of your documentation I think would leave even Sir Humphrey perplexed.

I am not trying to be difficult, I just want to understand.

A context is used for uniquing (to always have one instance of a particular entity loaded in your memory).

So for example if you are fetching a graph of entities where you have Orders and for each Order the Customer is also fetched.

If multiple orders fetched have the same customer, more than one instance of that customer would be created, thus updating one of them won't affect the other instances, unless you use a context. If the entire graph is fetched into a Context, then all entities of the same Customer would reference only one instance.

The context should only be used in one thread. The context is meant to have a single entity INSTANCE with the same data for a given semantical context. And when we say "semantic" we mean "Logical", just to differentiate the word context from our object Context.

Thanks for the clarification. That makes it a lot clearer.

I have had a look at your examples but what would be nice is an extended example

• A Situtation without using a context

• The same situtation when using a context Your example of orders and customers would be good.

Might I suggest that you add terms like this to your FAQs. I am still unsure of a number of terms that you use. For example

Walaa wrote:

thus updating one of them won't affect the other instances, unless you use a context. If the entire graph is fetched into a Context,

To my mind a graph is something that is plotted with data points. Your use here is within another context so I am assuming that you mean something like a complete set of related entities. There is also injection, emitting etc which one can probably work out but this is like using an assumption which is probably correct but there is a chance it might not be. Working with a (even a relatively small) degree of uncertainity makes it difficult to focus on the real essential matters.

I am all in favour of disambiguation.

Hi Peter. Thanks for the suggestions. We will look into them (the example con context, the concepts, etc.). In general, the words used at framework (thus the manual) are those we learn at a computer school, so most people would know what a Predicate, Context, or Graph is. I thing (IMHO) that it would be difficult to make a glossary of every word (entity graph, inheritance, injection, relation, currency, graph, interface, etc.) as most of them have a meaning outside this world of programming . I got your point though.

daelmo wrote:

that it would be difficult to make a glossary of every word (entity graph, inheritance, injection, relation, currency, graph, interface, etc.) as most of them have a meaning outside this world of programming . I got your point though.

I have been in IT for many years and I qualified when C was a just available with only man pages for documentation and the latest PC was an Apple II. I am sure there are others who not conversant with all the latest terminology. I know what an entity is, what concurrency, a relation, inheritance, interface and similar OOP terms are but some of these like a graph, injection I am not familar with. Maybe you can point me at a good online source to dispel my ignorance.

I had a hunt around on the web and found that my education was indeed lacking. Nevertheless I am doing an IT Masters and am still not conversant with all the terms required to fully appreciate your documentation. Maybe when I get to object modelling and design patterns I will get to these concepts.

For injection I found

Injection and Inversion

http://neelzone.wordpress.com/2007/04/04/injection-and-inversion/

for object graphs I found

Understanding C# Object Serialization and Object Graphs

http://www.informit.com/articles/article.aspx?p=1191548 (web page 6)

Interestingly the author of the last web article (Stephen B. Morris) states and I quote

I’m often struck by the overuse of complex terms to describe what are in fact simple concepts—persistence layer, web tier, servlet filters, etc. The term persistence layer basically refers to the area of code that interacts with some persistent storage—usually a relational database. The web tier is the section of software that provides web access. Servlet filters refer to the URLs processed by a web application/servlet.

Each such term is readily understood when it’s explained in a simple way. So why is the software industry permeated to such an extent with unnecessary complexity? Some clues to this need for obfuscation can perhaps be found if we look at other industries, such as the financial sector. I often listen to the analysts on Bloomberg.com, and after a few years I’ve begun to understand the secret language of "yields," "going long," "derivatives," and so on. It seems that as an industry matures, so does its appetite for jargon, and maybe this is happening in the software sector. It’s hard enough trying to understand the technology without having to first translate the descriptions! Excessive complexity in many ways is the enemy of widespread adoption. End of soapbox.

I can't help but agree with Stephen B. Morris

Agreeing with Stephen B Morris is one thing being able to clarify some aspects of LLBLGen Pro is another.

Most the ideas in the documentation are ok but I think some need extra clarification with examples.

I have had a look at the injection of dependent objects. I can see how you handle this declaratively but if you want to handle this programmatically its still a little vague. As far as I can see the various class that are injected are helper classes that one can assign to an entity class/object or one uses overriden methods.

In you documentation you have on page 74 // C# DependencyInjectionInfoProviderSingleton.PerformDependencyInjection(this);

I tried to find this in your examples but failed to do so. I can find examples of using this idea of injection in config files and in [attributes] but not the above.

Sorry if I am from the old computer school but some of these ideas appear that one needs a phd in both linguistics and computer science. I had a look at the documentation of one of your competitors and they do explain things much better than you. They had some nice features but in my estimation/opinion their product was not as comprehensive or as functional otherwise I would move over to them.

Can you please provide me a simple example of how one injects a validation class into an existing entity object programmatically.

Your initial tutorial is great for the basics. Can you please devise a medium level and advanced tutorial for some of the many other features in LLBLGen Pro. I think these are really great but don't want to waste a lot of time using an empirical approach in order to learn how to use them. It just leads to a great deal of frustration and a waste of time. I want to take advantage of the 50% in time saving that you promote.

I have trawled through the forums looking for issues with context. It would appear I am not the only one who has difficulties trying to come to grips with this concept.

From the discussions, it would appear that one uses a context to preserve changes to made to entities that have not been persisted back to the datastore and one needs to fetch additional entities or dependent entities from the datastore. One does not want to lose the changes one has made in fetching the others entities. I can see that this would be important in a transactional context in that the updating of dependent entities may be vary according to what is updated in a higher level entity.

One caveat in using a context is don't modify the primary key.

Am I getting warm or not.

As I mentioned before an example here of how a context can improve things or actually provide a solution to a particular problem would be very useful. As far as I can tell, you have code snippit examples but no actual project that can be downloaded and be used to walk one through the concept.

Let's answer your questions one at a time.

In you documentation you have on page 74 // C# DependencyInjectionInfoProviderSingleton.PerformDependencyInjection(this);

I tried to find this in your examples but failed to do so. I can find examples of using this idea of injection in config files and in [attributes] but not the above.

Sorry if I am from the old computer school but some of these ideas appear that one needs a phd in both linguistics and computer science. I had a look at the documentation of one of your competitors and they do explain things much better than you. They had some nice features but in my estimation/opinion their product was not as comprehensive or as functional otherwise I would move over to them.

Can you please provide me a simple example of how one injects a validation class into an existing entity object programmatically.

Dependancy Injection is done declaratively, otherwise, you can just set the Validator property of the entity, the following is copied from the docs on how and where you may do this: Setting an entity's Validator

Setting an entity's Validator If you've decided to use Validator classes to place your validation logic in, you'll be confronted with the question: how to set the right Validator in every entity object? You've three options:

1- Setting the Validator property of an entity object manually. This is straight forward, but error prone: if you forget to set a validator, validation using this validator object isn't performed. Also, entities fetched in bulk into a collection are created using the factories so you have to alter these as well. You could opt for overriding OnInitializing in an entity to add the creation of the Validator class.

2- By overriding the Entity method CreateValidator. This is a protected virtual (Protected Overridable) method which by default returns null / Nothing. You can override this method in a partial class or user code region of the Entity class to create the Validator to use for the entity. The LLBLGen Pro runtime framework will take care of calling the method. One way to create an override for most entities is by using a template. Please see the LLBLGen Pro SDK documentation for details about how to write templates to generate additional code into entities and in separate files. Also please see Adding Adding your own code to the generated classes for details.

3- By using Dependency Injection. Using the Dependency Injection mechanism build into LLBLGen Pro, the defined Validators are injected into the entity objects for you. This option is the least amount of work.

he00273, please sum up in a list the terms you're having problems with. 'Context' is a term with many different definitions. DepedencyInjection and Inversion of Control are others. The documentation describes these terms and these definitions are the ones to use.

I know on the web there are many definitions of dependency injection and inversion of control, and many are wrong and confusing, contradicting etc. http://www.llblgen.com/documentation/2.6/hh_goto.htm#Concepts/concepts_diioc.htm

describes the DI and IoC terms. That page is there for precisely that reason. The Context: same thing. it's for uniquing, so getting the same entity object for the same entity instance (data). Nothing more, nothing less.

3- By using Dependency Injection. Using the Dependency Injection mechanism build into LLBLGen Pro, the defined Validators are injected into the entity objects for you. This option is the least amount of work.

Sounds good

// C# DependencyInjectionInfoProviderSingleton.PerformDependencyInjection(this);

I could not any example of where the above code snippet is used in your examples. I would like to see an example of where Dependency Injection is used imperatively. You have examples of where it is setup via configuration and declaratively. I am trying to understand your product in its entirety but when you document some features and fail to place it into the context of some working code it leads to a degree of frustration (maybe its just me).

I had a look at a video "[color value="FF0000"]LLBLGen Overview (Special Edition) V[/color]ideo" by David Betz at http://www.netfxharmonics.com/2006/03/LLBLGen-Overview-Special-Edition-Video.aspx

The above video was great it provided me with the ability to understand quite a few of the concepts (even if they are for version 1 of llblgen) in only 30 minutes. Your documentation is ok but its not very digestible (I know its a reference and not a book). I have spent some time (many hours) going over your documentation and its hard going. The 30 minutes spent watching that video was very well spent in my estimation. Its a shame that that there are not any more.

Just pointing me back to the documentation

I know on the web there are many definitions of dependency injection and inversion of control, and many are wrong and confusing, contradicting etc. http://www.llblgen.com/documentation/2.6/hh_goto.htm#Concepts/concepts_diioc.htm

describes the DI and IoC terms. That page is there for precisely that reason.

means I am directed back to where I am experiencing the same difficulties as before.

Yesterday I found the free book that is basically an extended tutorial on LLBLGen with SQL Server 2005. This is at http://www.lulu.com/josephchancellor. This was mentioned in the forums but some had trouble getting a copy.

I have not read all the book but this approach is great. The only problem is that he not going to update it to cover version 2+ of LLBLGen Pro.

The Context: same thing. it's for uniquing, so getting the same entity object for the same entity instance (data). Nothing more, nothing less.

It is still confusing. If you could illustrate by example a situation where using a context solved a problem that would be very useful. If you could do a before example without a context and then an after example, using a context that would be terrific.

If someone could take over from Joseph Chancellor and update his book to cover the new features in LLBLGen Pro and include the more advanced features that would do an enormous amount (IMHO) to persuade others to adopt LLBLGen Pro. I would certainly buy a copy (provided the cost was not ridiculous).

he00273 wrote:

// C# DependencyInjectionInfoProviderSingleton.PerformDependencyInjection(this);

I could not any example of where the above code snippet is used in your examples.

That's because you don't need to call that method. It's there to let the dependency injection (DI) mechanism do its job.

DI is done in two ways mostly: 1) through a call from the constructor (we use that method) 2) through a factory (used by for example structuremap (a di tool))

We use mechanism 1 because we also want to have DI when a developer does: CustomerEntity c = new CustomerEntity();

in llblgen pro, this still triggers the DI mechanism and objects are still injected into 'c' (e.g. a validator, an authorizer). With factory based mechanisms, this isn't the case.

I would like to see an example of where Dependency Injection is used imperatively. You have examples of where it is setup via configuration and declaratively. I am trying to understand your product in its entirety but when you document some features and fail to place it into the context of some working code it leads to a degree of frustration (maybe its just me).

What's not documented exactly? If you follow the documenation about dependency injection it's documented properly and should get you started. If you want to know how things work internally, that's an entirely different thing.

So if you expect us to document a call to the method you quoted above, I fear you'll be dissapointed, as it's not going to be documented because it's not of a user's concern.

I don't know what you mean with 'used imperatively'.

I had a look at a video "[color value="FF0000"]LLBLGen Overview (Special Edition) V[/color]ideo" by David Betz at http://www.netfxharmonics.com/2006/03/LLBLGen-Overview-Special-Edition-Video.aspx The above video was great it provided me with the ability to understand quite a few of the concepts (even if they are for version 1 of llblgen) in only 30 minutes. Your documentation is ok but its not very digestible (I know its a reference and not a book). I have spent some time (many hours) going over your documentation and its hard going. The 30 minutes spent watching that video was very well spent in my estimation. Its a shame that that there are not any more.

The documentation is over 600 pages, it's big because there are a lot of features to cover. If a user starts with concepts, then goes to designer and then to generated code, the user has seen the elements which are the foundation of the functionality of the runtime / generated code.

Not everyone likes the docs, but we can't write a lot of different versions so it fits every different person's taste. The learning curve is steep because ... there's a lot to learn as the feature set is huge and a lot of ground is covered.

I know it will be complex and hard to grasp at times, especially if (take no offence of this) one thinks about tables/sql for example and suddenly has to work with objects and fetch methods and adapters etc.: the mindset of the reader (e.g. you) then doesn't click instantly with the material at hand and the reader then tries to connect one another with the knowledge the reader already has. If this connecting-the-dots doesn't give satisfying results, it will be a frustrating experience at first.

The problem for us however is: every reader is different and it's impossible to write documentation which is clear for everybody: person X will understand our docs instantly, person Y will have a hard time. If we rewrite it for Y, person X likely will get confused etc.

I saw the video you mentioned, it gives a brief overview of how things work, but it's not a video which teaches you how to use things.

Just pointing me back to the documentation

I know on the web there are many definitions of dependency injection and inversion of control, and many are wrong and confusing, contradicting etc. http://www.llblgen.com/documentation/2.6/hh_goto.htm#Concepts/concepts_diioc.htm

describes the DI and IoC terms. That page is there for precisely that reason.

means I am directed back to where I am experiencing the same difficulties as before.

I don't follow. I point you to the documentation page which explains what the concept is of dependency injection. You say you have problems with that page/piece of documentation. I then can't see in your head what these problems are. Is the presented documentation wrong? Is it conflicting with itself? Or is it conflicting with an idea of the same term you already had ?

The Context: same thing. it's for uniquing, so getting the same entity object for the same entity instance (data). Nothing more, nothing less.

It is still confusing. If you could illustrate by example a situation where using a context solved a problem that would be very useful. If you could do a before example without a context and then an after example, using a context that would be terrific.

The context documentation contains a couple of examples how to use it and what's the point of using it. Have you read that page? If so, have you tried the simple examples on that page to see what they do? For example, fetch the same entity instance (data) into two entity objects (== entity class instances) which obviously results in two different objects with the same entity instance (data). What if you want to use the same entity object for the same entity instance (data) ? So altering it in place X will alter the same object as it's used in place Y? This is what 'uniquing' is all about: entity instance A with pk value 1 is fetched into 1 entity object, all subsequential fetches of A with pk 1 will not be fetched into different entity objects, but the same entity object (== entity class instance) is returned. This is what the context does: providing unique objects.

I have had a look at the updated code for Code for the Rapid C# Windows Development eBook (author Joseph Chancellor, co-ordinator JezzT) and that satisfies my query concerning validation.

I will look at the context documentation again.

As far as I can tell, once you fetch an entity or an entity collection, you can add this to a context object.

You can try and get a specific entity instance (using PK) from a context if it is not there you can then get it from the persistence store. You check this by using entity.IsNew().

You can use a context with some methods to fetch entities, if the entity is already in the context (checked by PK), it will not be replaced by the entity/entities returned by the method, otherwise the entity/entities from the persistant store will be added

Is this hot, warm or cold?

Warm. You explained how to use Context. But do you understand why to use Context in the first place?

It's a place to store entities in memory for sharing between different pieces of code of your applications, making sure they all access the same instance of each entity object.

Example of what Walaa explains: you fetch the customer "ALFKI" from the db into an entity object: CustomerEntity c = new CustomerEntity("ALFKI"); // if you're using adapter, fetch it here.

now, you need this customer again, so if you do: CustomerEntity c2 = new CustomerEntity("ALFKI"); // if you're using adapter, fetch it here.

you have the same data (== entity instance) into memory but into two entity objects (== entity class instances)

so if you manipulate c2.CompanyName, the entity instance in c is left untouched. This is in general not a problem, as processing logic typically first fetches the entities, manipulates them and persists the changes to the db. However, it can be that an entity is cached somewhere, or you want to make sure that in a semantical context of your functionality, there's just one entity object for every entity instance in-memory.

This is where the context steps in. So in the example above, if I have added 'c' to the context, I can obtain the same entity object and place it in c2 for "ALFKI", so when I then manipulate c2.CompanyName, it's manipulated also in c as c2 and c point to the same object in memory.

Again, it's in general not needed that much, as logic in general works with data as if it's unique for itself, but it can come in handy at times. Be aware that if you're using a context, you should realize that it can't be shared among threads.

So rule of thumb (as with all the features in llblgen pro): first try without it, see if you need it. If you come at a point in your application where you need to access the same entity object for the same entity instance, you know that there's a facility which offers that feature.

Thanks for the clarification.