jolie / docs

The Jolie Documentation files

Welcome to the Jolie open source project!

What's Jolie?

Jolie is a service-oriented programming language, designed to offer native abstractions for the development of microservices. See our website for more information and installation instructions.

Have you made something in or for Jolie? Please submit it to our awesome Jolie list!

Documentation 📔

See https://docs.jolie-lang.org/ for documentation on how to program with Jolie.

For documentation on the interpreter, see https://github.com/jolie/jolie/wiki/Interpreter-documentation.

Roadmap 📈

You can check our roadmap to see what's staged for the next release.

Contributing 💻

Jolie is an open source project based on community effort. Contributions and constructive discussions are always welcome, and we encourage you to join us! There are many ways in which you can contribute, including coding, improving our documentation, helping out with newcomers, or even event organisation.

Interested in contributing? Please check our contribution and organisation guide.

All interactions regarding the Jolie open source project are expected to follow the code of conduct.

Our contributors 👍

Thank you to all our contributors!

Code status 🧐

Get in touch 👋

Discussions can take place over different media.

• Our GitHub repository, in the forms of discussion threads, issues, and pull requests.
• E-mail, by sending an e-mail to [email protected]. Anybody can send to the group. You can also register to the e-mail group at this link: https://groups.google.com/g/jolie-devel.
• Chat or Audio/Video calls. See below for a link to our Discord server.

Discord

Join our Discord server.

docs's Issues

Javaservice page links to example do not work

Javaservice page links to example do not work

Issues in section "Termination and Compensation"

Hello,
I found some issues in the section "Termination and Compensation" for Jolie 1.10.x.
I'm going to list them here:

• the image in "Termination and Compensation: concepts" is not shown in the documentaion website (but it does get shown in the markdown file) since the path is incorrect;
• in the examples in sections Compensation, the primitive comp and Installation-time variable evaluation, under Basics > Fault Handling > Termination and Compensation either the install directive is matching a wrong fault or the wrong fault is thrown.
  See here (rows 179-201, 341-364).

Is the protocol structure http correct?

The structure of http protocol reported at the page

https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/protocols/http.html

doesn't match its use.

Looking at the file

https://github.com/jolie/jocker/blob/master/dockerAPI.ol

you can see that osc field isn't in the position explained by the previous document.

http parameters not indented correctly

https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/protocols/http.html

it seems that the http parameters are not indented correctly

Allowed comment format

During the code I discovered that the allowed comment formats are as in Java

// single line

/*
multiple
lines
*/

but the is no mention in the documentation.

javaservice page: code snippet is incomplete

The following code snippet is incomplete:

for( i = 0, i

Scheduler library - no decription for all the operations

https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/standard-library-api/scheduler.html#setCronJob

The operations haven't any description.

execution syntax

In the documentation, the allowed syntax is indicated as

execution {}

but in the recent article of Fabrizio, there is another form

execution :

Local locations

The documentation of local locations

https://docs.jolie-lang.org/documentation/locations/local.html

does not report on statically defined local locations, like local:/Calculator. Somebody up to dealing with it?

@jolie/developers

Syntax of allowed interface/operations inside outputPort / inputPort

Inside the example
https://github.com/jolie/jocker/blob/master/ExampleOrchestrator/clientHello.ol

for joker

we could find a legacy syntax (???) for the interfaces in outputPort:

...

outputPort p {
...
RequestResponse: get
}

main {
get@p()(response);
println@Console(response)()
}

Shall we update the documentation about the syntax of outputPort/inputPort or modify the example and remove from the parser the old syntax?

Time - sleep no description

https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/standard-library-api/time.html#sleep

The operation has no description.

The input parameter is not described too.
Usually, it is expressed in milliseconds.

Repeated results in search

Hi @thesave

I noticed a problem with the gitbook search facilities it gives always the same resuts

Regards
Balint

Data Structure - literals custom datatype - assigning

In the page https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/basics/data_structures.html

after the section "<< - copying an entire tree structure" we could insert a section "Using the custom data type literals" with the following content (be free to modify and integrate the content)

In the call of an operation (example op@Service(request_data) (response_data), or in an assignent,
you can specify the literal of the custom type.

So you can write

x = 10
;
x.y = 12L
;
x.z = true

op@Service(x)(response)

or
op@Service(10{.y = 12L, .z = true}

If you are assign a literal to a variable REMEMBER to use the << operator

so x << 10 {.y = 12L, .z = true}

NOTE: it's common, coming from other language to write
x = 10 {.y = 12L, .z = true}

The interpreter will not give any type of error but at the execution time the value x.y will be undefined.

This is because x is associated only with the root value (10) and the tree of the children has not been copied inside x.

Instruction exit missing in documentation

The instruction exit is not explained in the documentation.

Example not complete in Javaservice page

This example is not complete:

package example;

import jolie.runtime.JavaService;
import jolie.net.CommMessage;
import jolie.runtime.Value;
import jolie.runtime.ValueVector;

public class JavaExample extends JavaService {

    public void start(){
        String s_string = "a_steaming_coffee_cup";
        String s_regExpr = "_";

        Value s_req = Value.create();
        s_req.getNewChild("string").setValue(s_string);
        s_req.getNewChild("regExpr").setValue(s_regExpr);

        try {
            System.out.println("Sent request");
            Value s_array = getEmbedder().callRequestResponse( "split", s_req );
            System.out.println("Received response");

            Value s_array = response.value();
            ValueVector s_children = s_array.getChildren("s_chunk");
            for( int i = 0; i

Complete jpm-jolie

The tutorial https://github.com/jolie/docs/blob/v1.10.x/web/tutorials/jpm-jolie.md needs to be completed.

Integration of the section about the alias (->)

Page: https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/basics/data_structures.html

After the section "-> - structures aliases", I suggest to insert
the following considerations.

Title: Beware of ->

a -> b

where b is a custom data type,is a lazy reference not a pointer to the node.

L'espression on the right of -> will be evaluated evaluated every time you are going to use the reference a.

So we could say a is a lazy reference.

Consider the following use:

define push_env {
__name = "env-" + __deepStack
;
prev_env -> __environment.(__name)
;
__deepStack++
;
__name = "env-" + __deepStack
;
__environment.(__name) = __name
;
env -> __environment.(__name)
}

the idea is to have __environment as a root where every child variable represent an environment of execution.

if we evaluate prev_env and env at the end of the routine we will find that they have the same value.

prev_env is evaluated as __environment.(__name)

same expression of env.

If you are going to use static path (not dynamic) this type of problem will not arise, but if you are using dynamic look-up be careful of the type of implementation.

Time.ol Documentation

@thesave @jolie/developers

Hey there how are I did find a few problems in decoding the information for the time.iol
for example

type ScheduleTimeOutRequest: int { 
    .message?: undefined
    .operation?: string
    .timeunit?: string
}

it is difficult to know what value to assign to timeunit, the only way I found to figure out what to use was to open the Jolie Project

Another example is setNextTimeoutByDateTime( undefined )

the actual code in the repository is

public void setNextTimeoutByDateTime( Value request )
	{
		long waitTime = 0;
		try {
			synchronized( dateTimeFormat ) {
				Date date = dateTimeFormat.parse( request.strValue() );
				waitTime = date.getTime() - (new Date()).getTime();
			}
		} catch( ParseException e ) {}

In general the documentation kinds of assumes that the Jolie Programmer know how to read and program in Java
Would be nice to insert one line of explanation on what the operation does so that the programmer does not have to "interpret" the functionality from the name
If you need a hand to add new information I am here just assign me the task

regards
Balint

Operation description not correct - list@File

The operation description in copied from StringUtils, and doesn't represent the correct semantic.

Please look at the pull request I am going to submit to fix this.

standard library not aligned

it seems that the standard library into the documentation is not aligned with the actual one in the repo.

ex: RuntimeService

Jolie v1.10 - Database - missing code in execption handler for update operation.

Sorry wrong signalation. I don't know how to delete this.

add header management doc in jolier

Docs about the management of extra headers in jolier are missing.

StringUtils calls - errorneous title descriptions

At the page https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/standard-library-api/string_utils.html#valueToPrettyString

The operation
valueToPrettyString

has the following description
Operation documentation: checks if the passed string starts with a given prefix

from the description is not immediately understandable that the operation transform a Jolie custom data type to a string
Invocation template:

valueToPrettyString@StringUtils( request )( response )

Post upgrade problem with documentation

@thesave .
I think something happened in the documentation

Input operations now we that unformatted text

Cheers
Balint

Wrong links in Protocol page (HTTPS, SODEPS)

In the page

https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/protocols/ssl/

the links embedded inside the following line (SODEPS , HTTPS)

SSL (Secure Sockets Layer) is not a communication protocol on its own and it is used as a wrapping for SSL-based secure protocols, like SODEPS and HTTPS.

are not working (wrong redirection)

Data structure - erasing tree structure: need to be integrated

Page: https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/basics/data_structures.html

Section: undef - erasing tree structures

It could be improved with the following consideration:

WARNING:
undef ( ) do not remove the structure it is aliasing,
only undefine the alias used (it is not pointing to the node previously

For example

include "console.iol"

main {
a.b.c.d.e = 12
;
a.b.c = 14
;
p -> a.b.c
;
println@Console(p)()
;
undef(p)
;
println@Console(a.b.c)()
;
println@Console(a.b.c.d.e)()
}

the code shows that after the operation undef on p, the original data path is invariant.

Installing Jolie from sources (tab "compile from sources")

https://www.jolie-lang.org/downloads.html

When installing jolie from source (Ubuntu/Linux subsystem in Windows)

I have noticed that there is an imprecision in the guide.

After running

scripts / dev-setup.sh ~ / bin

running jolie --version produces the notoriuous error

"Error: Could not find or load main class jolie.Jolie"

This type of error is mentioned in the installation procedure with the installer, and not in the topic "installing from from the sources".

Inside the system the isn't the path (/usr/lib/jolie) suggested by the guide to corret the problem (see below)

echo 'export JOLIE_HOME = "/usr/lib/jolie"' >> ~ / .bash_profile

To solve the problem the user has to set in .bashrc (.bash_profile or in /etc/.profile or /etc/bash_bashrc)
the follow line
export JOLIE_HOME=/dist/jolie

where is the path in the filesystem where you have cloned the project.

StringUtils - duplicate description of operations

A lot of operations have the same description.

It would be nice if there would be a description of the meaning of input/output parameters and of their value domains (example rightPad use a node char that need to be set to the encoding character set, but this is not indicated in the documentation).

Another nice improvement would be to append to each instruction a little example.

Missing link in Protocols

Inside the page https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/protocols/, at the paragraph

Let us recall the examples given in HTTP GET/POST Requests

the link associated with HTTP GET/POST is not correct

Add definition of session in Glossary

At the present the definition of session is missing from Glossary, it should be better to add it

publi and private service

Specify the difference between a public service and a private service here

https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/basics/services.html

Broken link in Rest

In the section https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/rest/, item "A Jolie router for mapping rest methods into Jolie operations" the following link is broken:

https://github.com/jolie/docs/tree/995bf15f2ee50877e8722867c19c5c8871b48116/rest/jester.md

Automatic creation of PDF version - Automatic creation of book

It would be very nice to have a button to generate the pdf version from the single page.

Like in Wikibooks, could we introduce the function that assembles all the docs page in a comphensive book?

String - multiple line format allowed - escape character

Could we explicitly indicate that the string could be splitted in multiple lines as from the following example?

jsonValue = "{
	\"int\": 123,
	\"bool\": true,
	\"long\": 124,
	\"double\": 123.4,
	\"string\": \"string\",
	\"void\": {},
	\"array\": [123, true,\"ciccio\",124,{}],
	\"obj\" : {
		\"int\": 1243,
		\"bool\": true,
		\"long\": 1234,
		\"double\": 1234.4,
		\"string\": \"string\",
		\"void\": {}
		}
	}"
;

I find useful that the documentation indicate that allowed standard operating use of the escape character inside the string content.

Jolie v1.10 - Leonardo - Incomplete code for length operation

At the page https://docs.jolie-lang.org/v1.10.x/language-tools-and-standard-library/web-applications/leonardo.html

the example for length operation is incomplete (some code missing).

Standard library - insert the include statement in the header.

Improvement for the section standard library.

For every library could be useful to see the include instruction, so if the include file has a name different from the spelling of the library (e.g. json_utils.iol -> JsonUtils) it would be immediately evident, and the programmer has not to search in the include folder.

Allowed name of variables

In the tutorial, there isn't a short section about the allowed name of variables.

So during the code, I discovered that _ is an allowed heading character.

I suggest, to introduce this section, explaining, officially the format of the allowed variable's names