Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

DevelopingOslc4Js

This page contains general notes on JavaScript, Node.js and various other technologies or dependent modules OSLC4JS may depend on. This is a general reference with links for additional information, as well as discussions about the pros and cons of various technology options. It is however not intended to provide detailed or tutorial information on using these technologies. Rather this section focuses on things that may be unique to OSLC4JS.

OSLC and Related Specifications

First and foremost, OSLC4JS depends on the OSLC specifications. This implementation will focus on OSLC 3.0 specifications since they are built on the layering of the WWW (URI, HTTP, REST) and W3C LDP.

Initially OSLC4JS will focus on these specifications

  1. W3C Linked Data Platform 1.0
  2. OSLC Core 3.0
  3. OSLC Change Management 3.0

Some General Notes on JavaScript

Node.js

Node.js is fundamental to OSLC4JS since OSLC resource access generally involves I/O over networks and therefore must be done asynchronously. Node.js provides the framework for developing asynchronous JavaScript applications. This is a very different programming model than those coming from the Java world will be familiar with. Asynchronous programming in Node.js is essentially event based programming that relies on callback functions that are invoked when an operation completes. As a result, code development and debugging is quite different because the code does not execute as it reads. An asynchronous call registers its callback function in the event loop and returns immediately. The programmer cannot predict when the callback will be actually invoked.

Instead of executing code in a simple, synchronous, linear fashion, Node recognizes that most IO operations take significantly longer than in-memory operations and does these calls asynchronously so that the application is not stuck waiting for IO. This programming style is a different thought process and makes debugging a bit harder because the code does not read as it is executed. But it is a more realistic representation of how thing actually happen in the real world.

An asynchronous call always returns immediately. When the operation is completed, a callback function that is provided as an argument is invoked to do the next step.

  • Things that have to be done in a sequence have to use nested callbacks, or use async series to force the ordering of otherwise asynchronous functions.
  • callback functions can be defined before, after on in the call that requires them
  • define them inline if they are reasonably simple, not more than three levels of nesting, and don’t need to be called again somewhere else.
  • Nested callbacks in a function that need to refer to this of the function representing an instance of a class will need a variable such as _self set to this in order to access a specific outer scope.
  • to know what arguments the callback needs to provide, you have to read the documentation or implementation code for the call
  • callback functions should typically have two arguments: err and results. err represents an error return that can be tested when the callback is called. results represents the asynchronous “return” of the original function called. Keeping callbacks consistent allows them to be reused on different functions and easier to know what the arguments are.

Node Modules

Are defined in a hierarchy of folders containing node_modules folder. A node_modules folder contains:

  • package.json - describes the module
  • usually index.js - does the requires for all the module parts and is invoked automatically by the Node when it looks up a module
  • Module lookup starts in the current directory, then goes to node_modules, then works up the directory structure looking in any other node_modules subfolders until it looks in the global node installation.
  • modules export things that are intended to be used by the user of the module - either a function or function class.

module.exports is returned from require(). This can be set to a function class, or different parts of the module can be set as properties of module.exports in order to access more than one exported item - require(‘aModule’).someExportedThing.

modules can be required more than once in different modules in the same node process, but only the first one executes the module to initialize its contents (exports) - the rest return references to already initialized contents.

Synchronous Function Calls

There are however times when things have to be done in a certain order. There are techniques for using nested anonymous JavaScript functions with callbacks to force functions to be executed in a particular order. But the async may be useful for more complex situations. See this very nce async tutorial.

npm install async

Can be used in a browser or with Node.js.

async.map - map a collection to an asynchronous function, and call a callback when it is complete

async.filter - execute a filter on an array and call a callback with the results that match.

async.parallel - execute a set of asynchronous functions in parallel and call a callback when completed.

async.series - execute a set of asynchronous functions in a fixed series

REST and HTTP Access

All interactions between OSLC clients and servers involve REST calls. For OSLC 3, the OSLC resources are generally RDF resources based on LDP. There are many JavaScript and Node.js HTTP access modules, but [1] looks particularly good. See how to use the request module.

See Extending request to support FORM based authentication.

SSL

Many OSLC tools require secure access through SSL. To avoid having to deal with certificates, you can use strictSSL: false in the request default options.

Back to the top