Contexts

context is an object that stores settings and state information that can be used throughout your application. The platform context holds settings and state information for a given Carbon LDP™ server. An application context holds settings and state information for a given application on a Carbon server.

What is a context?

context object refers to the Carbon platform or Carbon application with which you are working. Context objects store settings and state information that can be used throughout your application. For example, server settings, such as the host for your Carbon platform server, are defined in the platform context. Authentication information and object schema are also stored in context objects.

The information that’s stored in the context objects is continually referenced by other objects, making them critical for the proper functioning of the SDK. Since the nature of HTTP is inherently stateless, context objects can also be useful for managing application state within the client. In addition to certain required context settings, for example, you can use the context objects to store arbitrary settings and state information that may be useful to your custom application.

Configuring settings and state information in a context object simplifies the programming process. Setting the server host or domain in the platform context, for example, allows you to use relative URIs throughout your code. This relative URIs will be resolved against the context, making your client-side code independent from the location of a given platform server.

Platform context

The platform context references the location of a Carbon platform server. It contains the host/domain of the server, and it gives you access to define and modify settings, authentication services and object schemas that will be available globally for the Carbon SDK modules to use.

 

Declare the platform context

The platform context belongs to the Carbon class. To declare a platform context you need to import Carbon from the carbonldp/Carbon library and create a new instance of the Carbon object.

import Carbon from "carbonldp/Carbon";

let carbonContext = new Carbon();
import Carbon from "carbonldp/Carbon";

let carbonContext:Carbon = new Carbon();
var carbonContext = Carbon();
Without making any changes to the platform context (the instancecarbonContext, declared above), you can now call the resolve() method on it to see the default URIs against which relative URIs will be resolved. E.g.:
 

console.log( carbonContext.resolve( "" ) );

 

The resolve() method resolves the relative URIs provided( “” ) to an absolute URI and prints, for examplehttps://example.org/platform/.

Application context

An application context references an application that exists within your platform. It belongs to the Carbon.App.Context class.

The application context allows you to set application-specific settings and information that will be shared and used by all the Carbon JavaScript modules and methods. You can use an application context to access the Documents and data within an application and you can use it to configure roles and agents specific to the application.

The application context also provides convenient access to any information that’s in its associated platform context. For more in-depth information about the class, see: Carbon.App.Context.

Getting an app context

Once you have your platform context declared, you can get the application context that will reference it. With this context you can use all the modules and methods available to the application to retrieve documents that live inside it, or create new ones, etc.

The following example adds to the previous example and shows how to retrieve the application context for an application named “test-app”. Note: To retrieve an application context, you need to have created the application in your Carbon platform server first. The easiest way to create an app is through the Workbench (GUI). You can also create an app using the REST API.


import Carbon from "carbonldp/Carbon";

let carbonContext = new Carbon();

carbonContext.apps.getAppContext( "test-app/" ).then(
    ( appContext ) => {
        appContext.resolve( "" ); // https://carbonldp.com/apps/test-app/
    }
);
import Carbon from "carbonldp/Carbon";
import * as App from "carbonldp/App";

let carbonContext:Carbon = new Carbon();

carbonContext.apps.getAppContext( "test-app/" ).then(
    ( appContext:App.Context ) => {
        appContext.resolve( "" ); // https://carbonldp.com/apps/test-app/
    }
);
var carbonContext = new Carbon();

carbonContext.apps.getAppContext( "test-app/" ).then(
    function( appContext ) {
        appContext.resolve( "" ); // https://carbonldp.com/apps/test-app/
    }
);
The apps.getAppContext() method returns a Promise that, when resolved, gives you the app context.

Access/Modify your contexts

Now that you have declared a platform context and retrieved an application context, it’s time to work with them. A platform context has some pre-defined, default settings, whereas an application context does not. After declaring them you can set new settings or modify/delete pre-existing ones.

Some of the pre defined settings of a platform context are:

  • domain: “carbonldp.com”
  • http.ssl: true
  • auth.method: Carbon.Auth.Method.TOKEN
  • platform.container: “platform/”
  • platform.apps.container: “apps/”
  • platform.agents.container: “agents/”
  • vocabulary: “vocabulary/#”

You can add as many custom settings as you wish to either a platform context or an application context. Remember, there are no predefined settings for an application context.

Following is an example of how to change a default platform context setting and how to add a custom setting to an application context.

import Carbon from "carbonldp/Carbon";

let carbonContext = new Carbon();
let appContext;

// Modify predefined setting of platform context...
carbonContext.setSetting( "domain", "myorganization.com" );

// Carbon application context set new setting
carbonContext.apps.getAppContext( "test-app/" ).then(
   ( appContext ) => {
      appContext.setSetting( "name", "Awesome-programmer" );
    console.log( appContext.getSetting( "name" ) ); // prints Awesome-programmer
   }
);

console.log( carbonContext.resolve( "" ) ); // prints https://myorganization.com/platform/
import Carbon from "carbonldp/Carbon";
import * as App from "carbonldp/App";

let carbonContext:Carbon = new Carbon();
let appContext:App.Context;

// Modify predefined setting of platform context...
carbonContext.setSetting( "domain", "myorganization.com" );

// Carbon application context set new setting
carbonContext.apps.getAppContext( "test-app/" ).then(
   ( appContext:App.Context ) => {
      appContext.setSetting( "name", "Awesome-programmer" );
    console.log( appContext.getSetting( "name" ) ); // prints Awesome-programmer
   }
);

console.log( carbonContext.resolve( "" ) ); // prints https://myorganization.com/platform/
var carbonContext = new Carbon();
var appContext;

// Modify predefined setting of platform context...
carbonContext.setSetting( "domain", "myorganization.com" );

// Carbon application context set new setting
carbonContext.apps.getAppContext( "test-app/" ).then(
   function( appContext ) {
      appContext.setSetting( "name", "Awesome-programmer" );
    console.log( appContext.getSetting( "name" ) ); // prints Awesome-programmer
   }
);

console.log( carbonContext.resolve( "" ) ); // prints https://myorganization.com/platform/
The setSetting() method defines new settings or modifies preexisting settings in a context object. It receives two parameters: a string with name of the setting, and a value for the setting of any type. If the method called is used on a platform context, it will be a platform setting. Likewise, if it is used on an application context then it will be an application setting.

Inheritance

In this section we will discuss the inheritance of settings, authentication services and object schema defined in context objects. However, the object schema inheritance will be further discussed in the section extending the object schema of the object schema documentation.

An application context has access to all settings, services and object schemas contained in the platform context, unless those settings are explicitly overwritten. This means that when there is an attempt to access a setting in an application context, it is retrieved first from it. If the given setting is not defined in that application context, then it is retrieved from its associated platform context. If the setting is not found in either of the two, it means the setting has not been defined. This type of inheritance is similar to JavaScript’s prototypal inheritance.

The following example illustrates the inheritance of context settings – assuming two Carbon applications: test-app and your-app.

import Carbon from "carbonldp/Carbon";

let carbonContext = new Carbon();
let testAppContext;
let yourAppContext;

// Get your application contexts
carbonContext.apps.getAppContext( "test-app/" ).then(
    ( appContext ) => {
        testAppContext = appContext;
        return carbonContext.apps.getAppContext( "your-app/" );
       }
).then(
    ( appContext ) => {
        yourAppContext = appContext;

        // The name setting has not yet been set and it is not predefined in the platform or app contexts...
        carbonContext.getSetting( "name" );  // returns null
        testAppContext.getSetting( "name" ); // returns null
        yourAppContext.getSetting( "name" ); // returns null


        // Set 'name' setting in test-app app context...
        testAppContext.setSetting( "name", "TestApp" );
        carbonContext.getSetting( "name" );  // returns null
        testAppContext.getSetting( "name" ); // returns 'TestApp'
        yourAppContext.getSetting( "name" ); // returns null


        // Set 'name' setting in the platform context...
        carbonContext.setSetting( "name", "CarbonPlatform" );

        carbonContext.getSetting( "name" );  // returns 'CarbonPlatform'
        testAppContext.getSetting( "name" ); // returns 'TestApp'
        yourAppContext.getSetting( "name" ); // returns 'CarbonPlatform'

        // Deleting an app setting...
        testAppContext.deleteSetting( "name" );

        carbonContext.getSetting( "name" );  // returns 'CarbonPlatform'
        testAppContext.getSetting( "name" ); // returns 'CarbonPlatform'
        yourAppContext.getSetting( "name" ); // returns 'CarbonPlatform'
    }
);
import Carbon from "carbonldp/Carbon";
import * as App from "carbonldp/App";

let carbonContext:Carbon = new Carbon();
let testAppContext:App.Context;
let yourAppContext:App.Context;

// Get your application contexts
carbonContext.apps.getAppContext( "test-app/" ).then(
    ( appContext:App.Context ) => {
        testAppContext = appContext;
        return carbonContext.apps.getAppContext( "your-app/" );
       }
).then(
    ( appContext:App.Context ) => {
        yourAppContext = appContext;

        // The name setting has not yet been set and it is not predefined in the platform or app contexts...
        carbonContext.getSetting( "name" );  // returns null
        testAppContext.getSetting( "name" ); // returns null
        yourAppContext.getSetting( "name" ); // returns null


        // Set 'name' setting in test-app app context...
        testAppContext.setSetting( "name", "TestApp" );
        carbonContext.getSetting( "name" );  // returns null
        testAppContext.getSetting( "name" ); // returns 'TestApp'
        yourAppContext.getSetting( "name" ); // returns null


        // Set 'name' setting in the platform context...
        carbonContext.setSetting( "name", "CarbonPlatform" );

        carbonContext.getSetting( "name" );  // returns 'CarbonPlatform'
        testAppContext.getSetting( "name" ); // returns 'TestApp'
        yourAppContext.getSetting( "name" ); // returns 'CarbonPlatform'

        // Deleting an app setting...
        testAppContext.deleteSetting( "name" );

        carbonContext.getSetting( "name" );  // returns 'CarbonPlatform'
        testAppContext.getSetting( "name" ); // returns 'CarbonPlatform'
        yourAppContext.getSetting( "name" ); // returns 'CarbonPlatform'
    }
);
var carbonContext = new Carbon();
var testAppContext;
var yourAppContext;

// Get your application contexts
carbonContext.apps.getAppContext( "test-app/" ).then(
    function( appContext ) {
        testAppContext = appContext;
        return carbonContext.apps.getAppContext( "your-app/" );
       }
).then(
    function( appContext ) {
        yourAppContext = appContext;

        // The name setting has not yet been set and it is not predefined in the platform or app contexts...
        carbonContext.getSetting( "name" );  // returns null
        testAppContext.getSetting( "name" ); // returns null
        yourAppContext.getSetting( "name" ); // returns null


        // Set 'name' setting in test-app app context...
        testAppContext.setSetting( "name", "TestApp" );
        carbonContext.getSetting( "name" );  // returns null
        testAppContext.getSetting( "name" ); // returns 'TestApp'
        yourAppContext.getSetting( "name" ); // returns null


        // Set 'name' setting in the platform context...
        carbonContext.setSetting( "name", "CarbonPlatform" );

        carbonContext.getSetting( "name" );  // returns 'CarbonPlatform'
        testAppContext.getSetting( "name" ); // returns 'TestApp'
        yourAppContext.getSetting( "name" ); // returns 'CarbonPlatform'

        // Deleting an app setting...
        testAppContext.deleteSetting( "name" );

        carbonContext.getSetting( "name" );  // returns 'CarbonPlatform'
        testAppContext.getSetting( "name" ); // returns 'CarbonPlatform'
        yourAppContext.getSetting( "name" ); // returns 'CarbonPlatform'
    }
);

Conclusion

context is an object that stores settings and state information that can be used throughout your application. The two types of contexts are platform context and application context. Contexts follow an inheritance similar to the JavaScript’s prototypal inheritance. Settings and state information can be defined in the platform context to be used globally throughout your Carbon platform and information can be defined in the application context to be used in a specific application. Contexts are fundamental to interacting with your Carbon platform server using the JavaScript SDK.